/ Hex Artifact Content
Login

Artifact 984b1a39bc5f977aaf7ae1a7895ba2fdd5c4302a:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69 73  3_close()].** is
23f0: 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e   its destructor.
2400: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
2410: 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   other interface
2420: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73  s (such as.** [s
2430: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2440: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  2()], [sqlite3_c
2450: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2460: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2470: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
2480: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74  )] to name but t
2490: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d  hree) that are m
24a0: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20  ethods on an.** 
24b0: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a  sqlite3 object..
24c0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
24d0: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65  t sqlite3 sqlite
24e0: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  3;../*.** CAPI3R
24f0: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
2500: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57  er Types.** KEYW
2510: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
2520: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2530: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
2540: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
2550: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
2560: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
2570: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
2580: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
2590: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
25a0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
25b0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
25c0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
25d0: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
25e0: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
25f0: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2600: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  type definitions
2610: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f  ..** The sqlite_
2620: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2630: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
2640: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  e supported for 
2650: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
2660: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
2670: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2680: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
2690: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73  lite_int64 types
26a0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
26b0: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  er values.** bet
26c0: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36  ween -9223372036
26d0: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39  854775808 and +9
26e0: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
26f0: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e  07 inclusive.  ^
2700: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  The.** sqlite3_u
2710: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2720: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  _uint64 types ca
2730: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2740: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65  values .** betwe
2750: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37  en 0 and +184467
2760: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69  44073709551615 i
2770: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66  nclusive..*/.#if
2780: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
2790: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
27a0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
27b0: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
27c0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
27d0: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
27e0: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
27f0: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
2800: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
2810: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
2820: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
2830: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
2840: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2850: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
2860: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2870: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
2880: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
2890: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
28a0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
28b0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
28c0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
28d0: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
28e0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
28f0: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
2900: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
2910: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
2920: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
2930: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
2940: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
2950: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
2960: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
2970: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
2980: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
2990: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
29a0: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
29b0: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
29c0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
29d0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
29e0: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
29f0: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
2a00: 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
2a10: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2a20: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20   routine is the 
2a30: 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
2a40: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
2a50: 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ect..** ^Calls t
2a60: 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  o sqlite3_close(
2a70: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
2a80: 4f 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  OK if the [sqlit
2a90: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  e3] object is.**
2aa0: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65   successfully de
2ab0: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20  stroyed and all 
2ac0: 61 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f 75  associated resou
2ad0: 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63  rces are dealloc
2ae0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ated..**.** Appl
2af0: 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b 73  ications must [s
2b00: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
2b10: 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20  | finalize] all 
2b20: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b30: 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  ents].** and [sq
2b40: 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
2b50: 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42   | close] all [B
2b60: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73  LOB handles] ass
2b70: 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20  ociated with.** 
2b80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2b90: 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74  ject prior to at
2ba0: 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73  tempting to clos
2bb0: 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e  e the object.  ^
2bc0: 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c  If.** sqlite3_cl
2bd0: 6f 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ose() is called 
2be0: 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  on a [database c
2bf0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20  onnection] that 
2c00: 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74  still has.** out
2c10: 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72  standing [prepar
2c20: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 6f  ed statements] o
2c30: 72 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  r [BLOB handles]
2c40: 2c 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e  , then it return
2c50: 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59  s.** SQLITE_BUSY
2c60: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71 6c  ..**.** ^If [sql
2c70: 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73  ite3_close()] is
2c80: 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61   invoked while a
2c90: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2ca0: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61  open,.** the tra
2cb0: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
2cc0: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
2cd0: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   back..**.** The
2ce0: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   C parameter to 
2cf0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
2d00: 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  )] must be eithe
2d10: 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
2d20: 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74  ter or an [sqlit
2d30: 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74  e3] object point
2d40: 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  er obtained.** f
2d50: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  rom [sqlite3_ope
2d60: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
2d70: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  pen16()], or.** 
2d80: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2d90: 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65  ()], and not pre
2da0: 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a  viously closed..
2db0: 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
2dc0: 74 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74 68  te3_close() with
2dd0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2de0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a 2a  argument is a .*
2df0: 2a 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  * harmless no-op
2e00: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2e10: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a  _close(sqlite3 *
2e20: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
2e30: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
2e40: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
2e50: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
2e60: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
2e70: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
2e80: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
2e90: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
2ea0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
2eb0: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
2ec0: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
2ed0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
2ee0: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
2ef0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f00: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
2f10: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
2f20: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65  erface.**.** The
2f30: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
2f40: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
2f50: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
2f60: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
2f70: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2f80: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
2f90: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
2fa0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
2fb0: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
2fc0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
2fd0: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
2fe0: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
2ff0: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
3000: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
3010: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
3020: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
3030: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
3040: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
3050: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
3060: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
3070: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
3080: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
3090: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
30a0: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
30b0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
30c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30d0: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
30e0: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
30f0: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
3100: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3110: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
3120: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
3130: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3140: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
3150: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
3160: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
3170: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
3180: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
3190: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
31a0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
31b0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
31c0: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
31d0: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
31e0: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
31f0: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
3200: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
3210: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
3220: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
3230: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
3240: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
3250: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
3260: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
3270: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
3280: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3290: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
32a0: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
32b0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
32c0: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
32d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
32e0: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
32f0: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
3300: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
3310: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
3320: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
3330: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
3340: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3350: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3360: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
3370: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
3380: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
3390: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
33a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
33b0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
33c0: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
33d0: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
33e0: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
33f0: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
3400: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
3410: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
3420: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
3430: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
3440: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
3450: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
3460: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3470: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73  meter of.** of s
3480: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3490: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
34a0: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
34b0: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
34c0: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
34d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
34e0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
34f0: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3500: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3510: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3520: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3530: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3540: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3550: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3560: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3570: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3580: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3590: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
35a0: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
35b0: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
35c0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
35d0: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
35e0: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
35f0: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3600: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3610: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3620: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3630: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3640: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3650: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3660: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3670: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3680: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3690: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
36a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
36b0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
36c0: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
36d0: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
36e0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
36f0: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3700: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3710: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3720: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3730: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3740: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3750: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3760: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3770: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3780: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3790: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
37a0: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
37b0: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
37c0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
37d0: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
37e0: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
37f0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3800: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3810: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3820: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3830: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3840: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3850: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
3860: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3870: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
3880: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
3890: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
38a0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
38b0: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
38c0: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
38d0: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
38e0: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
38f0: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
3900: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
3910: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
3920: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
3930: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
3940: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
3950: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
3960: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
3970: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
3980: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
3990: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
39a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
39b0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68  t insure that th
39c0: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
39d0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
39e0: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
39f0: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
3a00: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3a10: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
3a20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3a30: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74  t not close [dat
3a40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a50: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
3a60: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
3a70: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3a80: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
3a90: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3aa0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
3ab0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
3ac0: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
3ad0: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
3ae0: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
3af0: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
3b00: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
3b10: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
3b20: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
3b30: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
3b40: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
3b50: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
3b60: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3b90: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
3ba0: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
3bb0: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
3be0: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
3bf0: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
3c00: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
3c10: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
3c20: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
3c30: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3c60: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
3c70: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
3c80: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
3cb0: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
3cc0: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
3cd0: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
3ce0: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
3cf0: 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20  ORDS: SQLITE_OK 
3d00: 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72  {error code} {er
3d10: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
3d20: 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20  YWORDS: {result 
3d30: 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f  code} {result co
3d40: 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  des}.**.** Many 
3d50: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
3d60: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
3d70: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
3d80: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
3d90: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
3da0: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73  er to indicate s
3db0: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
3dc0: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
3dd0: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
3de0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
3df0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
3e00: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
3e10: 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  so: [SQLITE_IOER
3e20: 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
3e30: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c  d result codes],
3e40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  .** [sqlite3_vta
3e50: 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
3e60: 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43   [SQLITE_ROLLBAC
3e70: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
3e80: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
3e90: 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20  LITE_OK         
3ea0: 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73    0   /* Success
3eb0: 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a  ful result */./*
3ec0: 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72   beginning-of-er
3ed0: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65  ror-codes */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f  fine SQLITE_ERRO
3ef0: 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20  R        1   /* 
3f00: 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73  SQL error or mis
3f10: 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f  sing database */
3f20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f30: 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20  INTERNAL     2  
3f40: 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67   /* Internal log
3f50: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
3f60: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
3f70: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
3f80: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
3f90: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
3fa0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
3fb0: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
3fc0: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
3fd0: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
3fe0: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
3ff0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
4000: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
4010: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
4020: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
4030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4040: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
4050: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
4060: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
4070: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
4080: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
4090: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
40a0: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
40b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
40c0: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
40d0: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
40e0: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
40f0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
4100: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
4110: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
4120: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
4130: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
4140: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65  nterrupt()*/.#de
4150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4160: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
4170: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
4180: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
4190: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
41a0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
41b0: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
41c0: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
41d0: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
41e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
41f0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
4200: 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70     /* Unknown op
4210: 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f  code in sqlite3_
4220: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a  file_control() *
4230: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4240: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
4250: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
4260: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
4270: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
4280: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4290: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
42a0: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
42b0: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
42c0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
42d0: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
42e0: 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61      15   /* Data
42f0: 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63  base lock protoc
4300: 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ol error */.#def
4310: 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59  ine SQLITE_EMPTY
4320: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44         16   /* D
4330: 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79  atabase is empty
4340: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4350: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31  TE_SCHEMA      1
4360: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  7   /* The datab
4370: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
4380: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4390: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20  LITE_TOOBIG     
43a0: 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20   18   /* String 
43b0: 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20  or BLOB exceeds 
43c0: 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64  size limit */.#d
43d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
43e0: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a  STRAINT  19   /*
43f0: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f   Abort due to co
4400: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
4410: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  on */.#define SQ
4420: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20  LITE_MISMATCH   
4430: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79   20   /* Data ty
4440: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23  pe mismatch */.#
4450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
4460: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f  SUSE      21   /
4470: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69  * Library used i
4480: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64  ncorrectly */.#d
4490: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c  efine SQLITE_NOL
44a0: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a  FS       22   /*
44b0: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65   Uses OS feature
44c0: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20  s not supported 
44d0: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69  on host */.#defi
44e0: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20  ne SQLITE_AUTH  
44f0: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75        23   /* Au
4500: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69  thorization deni
4510: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4520: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20  LITE_FORMAT     
4530: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61   24   /* Auxilia
4540: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d  ry database form
4550: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  at error */.#def
4560: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45  ine SQLITE_RANGE
4570: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32         25   /* 2
4580: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
4590: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74  sqlite3_bind out
45a0: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65   of range */.#de
45b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41  fine SQLITE_NOTA
45c0: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20  DB      26   /* 
45d0: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74  File opened that
45e0: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
45f0: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4600: 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20  ne SQLITE_ROW   
4610: 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71        100  /* sq
4620: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4630: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61   another row rea
4640: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  dy */.#define SQ
4650: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20  LITE_DONE       
4660: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33   101  /* sqlite3
4670: 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69  _step() has fini
4680: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a  shed executing *
4690: 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f  /./* end-of-erro
46a0: 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a  r-codes */../*.*
46b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65  * CAPI3REF: Exte
46c0: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
46d0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
46e0: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
46f0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
4700: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
4710: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
4720: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
4730: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
4740: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
4750: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
4760: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
4770: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
4780: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
4790: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
47a0: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
47b0: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
47c0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
47d0: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
47e0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
47f0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
4800: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
4810: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
4820: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
4830: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
4840: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
4850: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
4860: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
4870: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
4880: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
4890: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
48a0: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
48b0: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
48c0: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
48d0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
48e0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
48f0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
4900: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
4910: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
4920: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
4930: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4940: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
4950: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
4960: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
4970: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
4980: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
4990: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
49a0: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
49b0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
49c0: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
49d0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
49e0: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
49f0: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
4a00: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
4a10: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
4a20: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
4a30: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
4a40: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
4a50: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
4a60: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4a70: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
4a80: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
4a90: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
4aa0: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
4ab0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
4ac0: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
4ad0: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
4ae0: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
4af0: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
4b00: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
4b10: 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  o..*/.#define SQ
4b20: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
4b30: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4b40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
4b50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4b60: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
4b70: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
4b80: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
4b90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ba0: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
4bb0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4bc0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
4bd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4be0: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
4bf0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4c00: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
4c10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4c20: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
4c30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4c40: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
4c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c60: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
4c70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4c80: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
4c90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ca0: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
4cb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4cc0: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
4cd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ce0: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
4cf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4d00: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
4d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d20: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
4d30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d40: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
4d50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4d60: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
4d70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4d80: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
4d90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4da0: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
4db0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4dc0: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
4dd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4de0: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
4df0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e00: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
4e10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e20: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
4e30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e40: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
4e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e60: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
4e70: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
4e80: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
4e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ea0: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
4eb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4ec0: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
4ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ee0: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
4ef0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f00: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
4f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f20: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
4f30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f40: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65  R | (17<<8)).#de
4f50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f60: 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20  R_SHMOPEN       
4f70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f80: 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65  R | (18<<8)).#de
4f90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4fa0: 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20  R_SHMSIZE       
4fb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4fc0: 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65  R | (19<<8)).#de
4fd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4fe0: 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20  R_SHMLOCK       
4ff0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5000: 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65  R | (20<<8)).#de
5010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5020: 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20  R_SHMMAP        
5030: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5040: 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65  R | (21<<8)).#de
5050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5060: 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20  R_SEEK          
5070: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5080: 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65  R | (22<<8)).#de
5090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
50a0: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
50b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
50c0: 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64  ED |  (1<<8)).#d
50d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
50e0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
50f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5100: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
5110: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5120: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5130: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5140: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5160: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20  CORRUPT_VTAB    
5170: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5180: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29  CORRUPT | (1<<8)
5190: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51a0: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
51b0: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
51c0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
51d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
51e0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
51f0: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
5200: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
5210: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5220: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
5230: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
5240: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
5250: 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  <8))../*.** CAPI
5260: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20  3REF: Flags For 
5270: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74  File Open Operat
5280: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
5290: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
52a0: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
52b0: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70   in the.** 3rd p
52c0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
52d0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
52e0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
52f0: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20  d.** in the 4th 
5300: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5310: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
5320: 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  pen] method..*/.
5330: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5340: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  PEN_READONLY    
5350: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20       0x00000001 
5360: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5370: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5380: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5390: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20  PEN_READWRITE   
53a0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20       0x00000002 
53b0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
53c0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
53d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
53e0: 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20  PEN_CREATE      
53f0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20       0x00000004 
5400: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5410: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5420: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5430: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
5440: 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20  E    0x00000008 
5450: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5460: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5470: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20  PEN_EXCLUSIVE   
5480: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20       0x00000010 
5490: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
54a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
54b0: 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20  PEN_AUTOPROXY   
54c0: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20       0x00000020 
54d0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
54e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
54f0: 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20  PEN_URI         
5500: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20       0x00000040 
5510: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5520: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5540: 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20  PEN_MAIN_DB     
5550: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20       0x00000100 
5560: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5570: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5580: 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20  PEN_TEMP_DB     
5590: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20       0x00000200 
55a0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
55b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
55c0: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
55d0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20       0x00000400 
55e0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
55f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5600: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
5610: 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20       0x00000800 
5620: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5630: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5640: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
5650: 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20       0x00001000 
5660: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5670: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5680: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20  PEN_SUBJOURNAL  
5690: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20       0x00002000 
56a0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
56b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
56c0: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
56d0: 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20  AL   0x00004000 
56e0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
56f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5700: 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20  PEN_NOMUTEX     
5710: 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20       0x00008000 
5720: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5730: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5740: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5750: 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20  PEN_FULLMUTEX   
5760: 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20       0x00010000 
5770: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5780: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5790: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
57a0: 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
57b0: 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20       0x00020000 
57c0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
57d0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
57e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
57f0: 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
5800: 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20       0x00040000 
5810: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5820: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5830: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5840: 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20  PEN_WAL         
5850: 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20       0x00080000 
5860: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5870: 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20  ./* Reserved:   
5880: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5890: 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30        0x00F00000
58a0: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
58b0: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
58c0: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
58d0: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
58e0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
58f0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
5900: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
5910: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
5920: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
5930: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
5940: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
5950: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
5960: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
5970: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
5980: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
5990: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
59a0: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
59b0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
59c0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
59d0: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
59e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
59f0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
5a00: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
5a10: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
5a20: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
5a30: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5a40: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
5a50: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
5a60: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
5a70: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
5a80: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
5a90: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
5aa0: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
5ab0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
5ac0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
5ad0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
5ae0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5af0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
5b00: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
5b10: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
5b20: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
5b30: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
5b40: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
5b50: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
5b60: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5b70: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
5b80: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
5b90: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
5ba0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5bb0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
5bc0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
5bd0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
5be0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
5bf0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
5c00: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
5c10: 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ().  The SQLITE_
5c20: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
5c30: 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72  OVERWRITE proper
5c40: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
5c50: 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f   after reboot fo
5c60: 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20  llowing a crash 
5c70: 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74  or power loss, t
5c80: 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e  he only bytes in
5c90: 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20   a.** file that 
5ca0: 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20  were written at 
5cb0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
5cc0: 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65  level might have
5cd0: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20   changed.** and 
5ce0: 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79  that adjacent by
5cf0: 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20  tes, even bytes 
5d00: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
5d10: 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75  sector are.** gu
5d20: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75  aranteed to be u
5d30: 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65  nchanged..*/.#de
5d40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5d50: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
5d60: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5d70: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
5d80: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
5d90: 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20  12              
5da0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
5db0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5dc0: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
5dd0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5de0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
5df0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20  _IOCAP_ATOMIC2K 
5e00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5e10: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
5e20: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5e30: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20  OMIC4K          
5e40: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
5e50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5e60: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
5e70: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5e80: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
5e90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5ea0: 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20  IC16K           
5eb0: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64     0x00000040.#d
5ec0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5ed0: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20  AP_ATOMIC32K    
5ee0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5ef0: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0080.#define SQL
5f00: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5f10: 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  64K             
5f20: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
5f30: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5f40: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
5f50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
5f60: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
5f70: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5f80: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30  AL             0
5f90: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e  x00000400.#defin
5fa0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
5fb0: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
5fc0: 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30  OPEN  0x00000800
5fd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fe0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
5ff0: 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30  OVERWRITE    0x0
6000: 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0001000../*.** C
6010: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
6020: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
6030: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
6040: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
6050: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
6060: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
6070: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
6080: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
6090: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
60a0: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
60b0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
60c0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
60d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
60e0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
60f0: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
6100: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
6110: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
6120: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6130: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
6140: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6150: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
6160: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
6170: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
6180: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
6190: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
61a0: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
61b0: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
61c0: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
61d0: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
61e0: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
61f0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6200: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
6210: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
6220: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
6230: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6240: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
6250: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
6260: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
6270: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
6280: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
6290: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
62a0: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
62b0: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
62c0: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
62d0: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
62e0: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
62f0: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
6300: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6310: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
6320: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6330: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
6340: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
6350: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
6360: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
6370: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
6380: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6390: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
63a0: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
63b0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
63c0: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
63d0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
63e0: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
63f0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
6400: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
6410: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
6420: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
6430: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
6440: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
6450: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
6460: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
6470: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
6480: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
6490: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
64a0: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
64b0: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
64c0: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
64d0: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
64e0: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
64f0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
6500: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6510: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6520: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
6530: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
6540: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
6550: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
6560: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
6570: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
6580: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
6590: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
65a0: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
65b0: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
65c0: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
65d0: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
65e0: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
65f0: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
6600: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
6610: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
6620: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
6630: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
6640: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
6650: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
6660: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
6670: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
6680: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
6690: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
66a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
66b0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
66c0: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
66d0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
66e0: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
66f0: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
6700: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
6710: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
6720: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
6730: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
6740: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
6750: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
6760: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
6770: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
6780: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
6790: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
67a0: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
67b0: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
67c0: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
67d0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
67e0: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
67f0: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
6800: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
6810: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
6820: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
6830: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
6840: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
6850: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
6860: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6870: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
6880: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
6890: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
68a0: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
68b0: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
68c0: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
68d0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
68e0: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
68f0: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
6900: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
6910: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
6920: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
6930: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
6940: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
6950: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
6960: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6970: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
6980: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
6990: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
69a0: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
69b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
69c0: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
69d0: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
69e0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
69f0: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
6a00: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
6a10: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
6a20: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
6a30: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
6a40: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
6a50: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
6a60: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
6a70: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
6a80: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
6a90: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6aa0: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6ab0: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6ac0: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6ad0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6ae0: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6af0: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
6b00: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
6b10: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
6b20: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
6b30: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
6b40: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
6b50: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
6b60: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6b70: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
6b80: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
6b90: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
6ba0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
6bb0: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
6bc0: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
6bd0: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
6be0: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
6bf0: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
6c00: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
6c10: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
6c20: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
6c30: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
6c40: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
6c50: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
6c60: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
6c70: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
6c80: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
6c90: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
6ca0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
6cb0: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
6cc0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
6cd0: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
6ce0: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
6cf0: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
6d00: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
6d10: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
6d20: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
6d30: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
6d40: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
6d50: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
6d60: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
6d70: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
6d80: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
6d90: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
6da0: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
6db0: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
6dc0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6dd0: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
6de0: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
6df0: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
6e00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6e10: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
6e20: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
6e30: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
6e40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
6e50: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
6e60: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6e70: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
6e80: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
6e90: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
6ea0: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
6eb0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
6ec0: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
6ed0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
6ee0: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
6ef0: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
6f00: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
6f10: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
6f20: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
6f30: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
6f40: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
6f50: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
6f60: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
6f70: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
6f80: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
6f90: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
6fa0: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
6fb0: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
6fc0: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
6fd0: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
6fe0: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
6ff0: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
7000: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
7010: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
7020: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
7030: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7040: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
7050: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
7060: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
7070: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
7080: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
7090: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
70a0: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
70b0: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
70c0: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
70d0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
70e0: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
70f0: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
7100: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
7110: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
7120: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
7130: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
7140: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
7150: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
7160: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
7170: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
7180: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
7190: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
71a0: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
71b0: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
71c0: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
71d0: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
71e0: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
71f0: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
7200: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
7210: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
7220: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
7230: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
7240: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
7250: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
7260: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
7270: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
7280: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
7290: 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  A [SQLITE_FCNTL_
72a0: 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74  LOCKSTATE | list
72b0: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
72c0: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
72d0: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
72e0: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
72f0: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
7300: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
7310: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
7320: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
7330: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
7340: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
7350: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7360: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
7370: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
7380: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
7390: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
73a0: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
73b0: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
73c0: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
73d0: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
73e0: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
73f0: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
7400: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
7410: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
7420: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
7430: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
7440: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
7450: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
7460: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
7470: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
7480: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
7490: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
74a0: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
74b0: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
74c0: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
74d0: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
74e0: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
74f0: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
7500: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7510: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7520: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
7530: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7540: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
7550: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7560: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
7570: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7580: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
7590: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
75a0: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
75b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
75c0: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
75d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
75e0: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
75f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7600: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
7610: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7620: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
7630: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
7640: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
7650: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7660: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
7670: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
7680: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7690: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
76a0: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
76b0: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
76c0: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
76d0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
76e0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
76f0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
7700: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
7710: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
7720: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
7730: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
7740: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
7750: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
7760: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
7770: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
7780: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
7790: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
77a0: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
77b0: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
77c0: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
77d0: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
77e0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
77f0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
7800: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
7810: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
7820: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
7830: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
7840: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
7850: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
7860: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
7870: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
7880: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
7890: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
78a0: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
78b0: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61  )..**.** If xRea
78c0: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  d() returns SQLI
78d0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
78e0: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f  EAD it must also
78f0: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20   fill.** in the 
7900: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20  unread portions 
7910: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69  of the buffer wi
7920: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53  th zeros.  A VFS
7930: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74   that.** fails t
7940: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
7950: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65  t reads might se
7960: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77  em to work.  How
7970: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65  ever,.** failure
7980: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
7990: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65  ort reads will e
79a0: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74  ventually lead t
79b0: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  o.** database co
79c0: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  rruption..*/.typ
79d0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
79e0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
79f0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7a00: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
7a10: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
7a20: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
7a30: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
7a40: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
7a50: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
7a60: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
7a70: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
7a80: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
7a90: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
7aa0: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
7ab0: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
7ac0: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
7ad0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
7ae0: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74    int (*xTruncat
7af0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7b00: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
7b10: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
7b20: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
7b30: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
7b40: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
7b50: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
7b60: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
7b70: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
7b80: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
7b90: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
7ba0: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
7bb0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7bc0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
7bd0: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
7be0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7bf0: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
7c00: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
7c10: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
7c20: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
7c30: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
7c40: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
7c50: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
7c60: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
7c70: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
7c80: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
7c90: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
7ca0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
7cb0: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74  rsion 1 */.  int
7cc0: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69   (*xShmMap)(sqli
7cd0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69  te3_file*, int i
7ce0: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e  Pg, int pgsz, in
7cf0: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65  t, void volatile
7d00: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  **);.  int (*xSh
7d10: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  mLock)(sqlite3_f
7d20: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74  ile*, int offset
7d30: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61  , int n, int fla
7d40: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53  gs);.  void (*xS
7d50: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74  hmBarrier)(sqlit
7d60: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7d70: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71   (*xShmUnmap)(sq
7d80: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7d90: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20   deleteFlag);.  
7da0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
7db0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
7dc0: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a  ersion 2 */.  /*
7dd0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
7de0: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
7df0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
7e00: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
7e10: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
7e20: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
7e30: 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54   Opcodes.**.** T
7e40: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
7e50: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
7e60: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
7e70: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
7e80: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
7e90: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7ea0: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
7eb0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
7ec0: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
7ed0: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
7ee0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
7ef0: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
7f00: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
7f10: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
7f20: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
7f30: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
7f40: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
7f50: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
7f60: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
7f70: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
7f80: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
7f90: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
7fa0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
7fb0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
7fc0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
7fd0: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
7fe0: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
7ff0: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8000: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8010: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8020: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8030: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8040: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8050: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
8060: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
8070: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
8080: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  .** is defined..
8090: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b  ** <ul>.** <li>[
80a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
80b0: 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65  ZE_HINT]].** The
80c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
80d0: 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65  IZE_HINT] opcode
80e0: 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69   is used by SQLi
80f0: 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56  te to give the V
8100: 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69  FS.** layer a hi
8110: 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20  nt of how large 
8120: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8130: 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62  e will grow to b
8140: 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  e during the.** 
8150: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
8160: 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ion.  This hint 
8170: 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  is not guarantee
8180: 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65  d to be accurate
8190: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66   but it.** is of
81a0: 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20  ten close.  The 
81b0: 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d  underlying VFS m
81c0: 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70  ight choose to p
81d0: 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62  reallocate datab
81e0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63  ase.** file spac
81f0: 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20  e based on this 
8200: 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  hint in order to
8210: 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20   help writes to 
8220: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
8230: 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e  file run faster.
8240: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8250: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
8260: 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SIZE]].** The [S
8270: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
8280: 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69  K_SIZE] opcode i
8290: 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73  s used to reques
82a0: 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a  t that the VFS.*
82b0: 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72  * extends and tr
82c0: 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61  uncates the data
82d0: 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75  base file in chu
82e0: 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70  nks of a size sp
82f0: 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
8300: 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72  e user. The four
8310: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  th argument to [
8320: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8330: 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a  trol()] should .
8340: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69  ** point to an i
8350: 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74  nteger (type int
8360: 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
8370: 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20   new chunk-size 
8380: 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68  to use.** for th
8390: 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61  e nominated data
83a0: 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67  base. Allocating
83b0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73   database file s
83c0: 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a  pace in large.**
83d0: 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42   chunks (say 1MB
83e0: 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79   at a time), may
83f0: 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73   reduce file-sys
8400: 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  tem fragmentatio
8410: 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65  n and.** improve
8420: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20   performance on 
8430: 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a  some systems..**
8440: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8450: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
8460: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
8470: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
8480: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
8490: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
84a0: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
84b0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
84c0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
84d0: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61  ciated with a pa
84e0: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
84f0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
8500: 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74    See the [sqlit
8510: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8520: 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  )] documentation
8530: 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
8540: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
8550: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
8560: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
8570: 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65  ITTED]].** ^(The
8580: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
8590: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63  YNC_OMITTED] opc
85a0: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
85b0: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a   internally by.*
85c0: 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e  * SQLite and sen
85d0: 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69  t to all VFSes i
85e0: 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c  n place of a cal
85f0: 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d  l to the xSync m
8600: 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68  ethod.** when th
8610: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
8620: 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d  ction has [PRAGM
8630: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73  A synchronous] s
8640: 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20  et to OFF.)^.** 
8650: 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64  Some specialized
8660: 20 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 73   VFSes need this
8670: 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72   signal in order
8680: 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72   to operate corr
8690: 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50  ectly.** when [P
86a0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
86b0: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
86c0: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73  ronous=OFF] is s
86d0: 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a  et, but most .**
86e0: 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65   VFSes do not ne
86f0: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61  ed this signal a
8700: 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  nd should silent
8710: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
8720: 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  pcode..** Applic
8730: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
8740: 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  t call [sqlite3_
8750: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
8760: 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63  with this.** opc
8770: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
8780: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
8790: 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
87a0: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
87b0: 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65  es.** that do re
87c0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
87d0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
87e0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
87f0: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
8800: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
8810: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
8820: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
8830: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
8840: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
8850: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
8860: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
8870: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
8880: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
8890: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
88a0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
88b0: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
88c0: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
88d0: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
88e0: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
88f0: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
8900: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
8910: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
8920: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
8930: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
8940: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
8950: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
8960: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
8970: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
8980: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
8990: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
89a0: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
89b0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
89c0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
89d0: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
89e0: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
89f0: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
8a00: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
8a10: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
8a20: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
8a30: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
8a40: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
8a50: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
8a60: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
8a70: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
8a80: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
8a90: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
8aa0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
8ab0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
8ac0: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
8ad0: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
8ae0: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
8af0: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
8b00: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
8b10: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
8b20: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
8b30: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
8b40: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
8b50: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
8b60: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
8b70: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
8b80: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
8b90: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
8ba0: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
8bb0: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
8bc0: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
8bd0: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
8be0: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
8bf0: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
8c00: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
8c10: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
8c20: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
8c30: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
8c40: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
8c50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
8c60: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
8c70: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
8c80: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
8c90: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
8ca0: 20 57 72 69 74 65 20 41 48 65 61 64 20 4c 6f 67   Write AHead Log
8cb0: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
8cc0: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
8cd0: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
8ce0: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
8cf0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
8d00: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
8d10: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
8d20: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
8d30: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
8d40: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
8d50: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
8d60: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
8d70: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
8d80: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
8d90: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
8da0: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
8db0: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
8dc0: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
8dd0: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
8de0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
8df0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
8e00: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
8e10: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
8e20: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
8e30: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
8e40: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
8e50: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
8e60: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
8e70: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
8e80: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
8e90: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
8ea0: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
8eb0: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
8ec0: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
8ed0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
8ee0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8ef0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
8f00: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
8f10: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
8f20: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
8f30: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
8f40: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
8f50: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
8f60: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
8f70: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
8f80: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
8f90: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
8fa0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
8fb0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
8fc0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
8fd0: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
8fe0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
8ff0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
9000: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
9010: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9020: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
9030: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
9040: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9050: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9060: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
9070: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
9080: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
9090: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
90a0: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
90b0: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
90c0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
90d0: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
90e0: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
90f0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
9100: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
9110: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
9120: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
9130: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
9140: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
9150: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
9160: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
9170: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
9180: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
9190: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
91a0: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
91b0: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
91c0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
91d0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
91e0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
91f0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
9200: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
9210: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
9220: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9230: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
9240: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
9250: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
9260: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
9270: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
9280: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
9290: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
92a0: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
92b0: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
92c0: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
92d0: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
92e0: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
92f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9300: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
9310: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
9320: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
9330: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
9340: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
9350: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
9360: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9370: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
9380: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9390: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
93a0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
93b0: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
93c0: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
93d0: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
93e0: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
93f0: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
9400: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
9410: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
9420: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
9430: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
9440: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
9450: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
9460: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
9470: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
9480: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
9490: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
94a0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
94b0: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
94c0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
94d0: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
94e0: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
94f0: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
9500: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
9510: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
9520: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
9530: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
9540: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
9550: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
9560: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
9570: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
9580: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
9590: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
95a0: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
95b0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
95c0: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
95d0: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
95e0: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
95f0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
9600: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
9610: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
9620: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
9630: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
9640: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
9650: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
9660: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
9670: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
9680: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
9690: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
96a0: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
96b0: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
96c0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
96d0: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
96e0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
96f0: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
9700: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
9710: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
9720: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
9730: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
9740: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
9750: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
9760: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
9770: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
9780: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
9790: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
97a0: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
97b0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
97c0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
97d0: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
97e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
97f0: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
9800: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
9810: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
9820: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
9830: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
9840: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
9850: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
9860: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
9870: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
9880: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
9890: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
98a0: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
98b0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
98c0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
98d0: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
98e0: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
98f0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
9900: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
9910: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
9920: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
9930: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
9940: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
9950: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
9960: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
9970: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
9980: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
9990: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
99a0: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
99b0: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
99c0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
99d0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
99e0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
99f0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
9a00: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
9a10: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
9a20: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
9a30: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
9a40: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
9a50: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
9a60: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
9a70: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
9a80: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
9a90: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
9aa0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
9ab0: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73  turns.** any res
9ac0: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74  ult code other t
9ad0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  han [SQLITE_OK] 
9ae0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  or [SQLITE_NOTFO
9af0: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  UND], that means
9b00: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53  .** that the VFS
9b10: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20   encountered an 
9b20: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64  error while hand
9b30: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  ling the [PRAGMA
9b40: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  ] and the.** com
9b50: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  pilation of the 
9b60: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74  PRAGMA fails wit
9b70: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68  h an error.  ^Th
9b80: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9b90: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
9ba0: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61  control occurs a
9bb0: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  t the beginning 
9bc0: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  of pragma statem
9bd0: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64  ent analysis and
9be0: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c   so.** it is abl
9bf0: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75  e to override bu
9c00: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20  ilt-in [PRAGMA] 
9c10: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 3c  statements..** <
9c20: 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /ul>.*/.#define 
9c30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
9c40: 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20  KSTATE          
9c50: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
9c60: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
9c70: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20  OXYFILE         
9c80: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
9c90: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_SET_LOCKPRO
9ca0: 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20  XYFILE          
9cb0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
9cc0: 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20  ITE_LAST_ERRNO  
9cd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
9ce0: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
9cf0: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
9d00: 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NT              
9d10: 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
9d20: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
9d30: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
9d40: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
9d50: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9d60: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37  TER            7
9d70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9d80: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
9d90: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a  ED            8.
9da0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
9db0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
9dc0: 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23  TRY          9.#
9dd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
9de0: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20  NTL_PERSIST_WAL 
9df0: 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
9e00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
9e10: 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  TL_OVERWRITE    
9e20: 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65            11.#de
9e30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
9e40: 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20  L_VFSNAME       
9e50: 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66           12.#def
9e60: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
9e70: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
9e80: 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69  RITE    13.#defi
9e90: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
9ea0: 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
9eb0: 20 20 20 20 20 20 20 31 34 0a 0a 2f 2a 0a 2a 2a         14../*.**
9ec0: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
9ed0: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68   Handle.**.** Th
9ee0: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
9ef0: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
9f00: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
9f10: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
9f20: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
9f30: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
9f40: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
9f50: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
9f60: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
9f70: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
9f80: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
9f90: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
9fa0: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
9fb0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
9fc0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
9fd0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
9fe0: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
9ff0: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
a000: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
a010: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
a020: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
a030: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
a040: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
a050: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
a060: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ject.**.** An in
a070: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71  stance of the sq
a080: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
a090: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
a0a0: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a  erface between.*
a0b0: 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * the SQLite cor
a0c0: 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c  e and the underl
a0d0: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
a0e0: 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73  ystem.  The "vfs
a0f0: 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65  ".** in the name
a100: 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73   of the object s
a110: 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75  tands for "virtu
a120: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e  al file system".
a130: 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46    See.** the [VF
a140: 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74  S | VFS document
a150: 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68  ation] for furth
a160: 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  er information..
a170: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
a180: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
a190: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
a1a0: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
a1b0: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
a1c0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
a1d0: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
a1e0: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
a1f0: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
a200: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
a210: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
a220: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
a230: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
a240: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
a250: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
a260: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
a270: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
a280: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
a290: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
a2a0: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
a2b0: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
a2c0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
a2d0: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
a2e0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
a2f0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
a300: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
a310: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
a320: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
a330: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
a340: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
a350: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
a360: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
a370: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
a380: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
a390: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
a3a0: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
a3b0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
a3c0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
a3d0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
a3e0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
a3f0: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
a400: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
a410: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
a420: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
a430: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
a440: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
a450: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
a460: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
a470: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
a480: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
a490: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
a4a0: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
a4b0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
a4c0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
a4d0: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
a4e0: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
a4f0: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
a500: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
a510: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
a520: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
a530: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
a540: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
a550: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
a560: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
a570: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
a580: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
a590: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
a5a0: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
a5b0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
a5c0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
a5d0: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
a5e0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
a5f0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
a600: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
a610: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
a620: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
a630: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
a640: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
a650: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
a660: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
a670: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
a680: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
a690: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
a6a0: 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c  .xOpen]].** ^SQL
a6b0: 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
a6c0: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
a6d0: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
a6e0: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
a6f0: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
a700: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
a710: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
a720: 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68  lPathname() with
a730: 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66   an optional suf
a740: 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49  fix added..** ^I
a750: 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64  f a suffix is ad
a760: 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65  ded to the zFile
a770: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20  name parameter, 
a780: 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69  it will.** consi
a790: 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22  st of a single "
a7a0: 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c  -" character fol
a7b0: 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65  lowed by no more
a7c0: 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68   than.** 11 alph
a7d0: 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20  anumeric and/or 
a7e0: 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a  "-" characters..
a7f0: 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68  ** ^SQLite furth
a800: 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  er guarantees th
a810: 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  at.** the string
a820: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
a830: 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74  nd unchanged unt
a840: 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a  il xClose() is.*
a850: 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73  * called. Becaus
a860: 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75  e of the previou
a870: 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74  s sentence,.** t
a880: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
a890: 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f  ] can safely sto
a8a0: 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  re a pointer to 
a8b0: 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  the.** filename 
a8c0: 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72  if it needs to r
a8d0: 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65  emember the file
a8e0: 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65  name for some re
a8f0: 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ason..** If the 
a900: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
a910: 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20  ter to xOpen is 
a920: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
a930: 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73  hen xOpen.** mus
a940: 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e  t invent its own
a950: 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20   temporary name 
a960: 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e  for the file.  ^
a970: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a  Whenever the .**
a980: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   xFilename param
a990: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20  eter is NULL it 
a9a0: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65  will also be the
a9b0: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a   case that the.*
a9c0: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  * flags paramete
a9d0: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b  r will include [
a9e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
a9f0: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a  TEONCLOSE]..**.*
aa00: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
aa10: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20  ment to xOpen() 
aa20: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74  includes all bit
aa30: 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20  s set in.** the 
aa40: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
aa50: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
aa60: 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73  v2()].  Or if [s
aa70: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
aa80: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
aa90: 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  en16()] is used,
aaa0: 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c   then flags incl
aab0: 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a  udes at least.**
aac0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
aad0: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
aae0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
aaf0: 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20   .** If xOpen() 
ab00: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
ab10: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
ab20: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
ab30: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
ab40: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
ab50: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
ab60: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
ab70: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
ab80: 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61   ^(SQLite will a
ab90: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
aba0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
abb0: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28  gs to the xOpen(
abc0: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e  ).** call, depen
abd0: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65  ding on the obje
abe0: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a  ct being opened:
abf0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
ac00: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
ac10: 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_MAIN_DB].** <l
ac20: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
ac30: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _MAIN_JOURNAL].*
ac40: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
ac50: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a  OPEN_TEMP_DB].**
ac60: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
ac70: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
ac80: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
ac90: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
aca0: 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  T_DB].** <li>  [
acb0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
acc0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
acd0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
ace0: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  STER_JOURNAL].**
acf0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
ad00: 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  PEN_WAL].** </ul
ad10: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  >)^.**.** The fi
ad20: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
ad30: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
ad40: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
ad50: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
ad60: 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c   the way it deal
ad70: 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46  s with files.  F
ad80: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  or example, an a
ad90: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68  pplication.** th
ada0: 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  at does not care
adb0: 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63   about crash rec
adc0: 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63  overy or rollbac
add0: 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20  k might make.** 
ade0: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f  the open of a jo
adf0: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d  urnal file a no-
ae00: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  op.  Writes to t
ae10: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  his journal woul
ae20: 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d  d.** also be no-
ae30: 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74  ops, and any att
ae40: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65  empt to read the
ae50: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72   journal would r
ae60: 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
ae70: 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69  IOERR.  Or the i
ae80: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
ae90: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
aea0: 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  at a database.**
aeb0: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f   file will be do
aec0: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
aed0: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
aee0: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
aef0: 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  ndom.** order an
af00: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
af10: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
af20: 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51  dingly..**.** SQ
af30: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
af40: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
af50: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
af60: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
af70: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
af80: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
af90: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
afa0: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
afb0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
afc0: 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  E].** </ul>.**.*
afd0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  * The [SQLITE_OP
afe0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
aff0: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
b000: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a   file should be.
b010: 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ** deleted when 
b020: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e  it is closed.  ^
b030: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
b040: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
b050: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66  ** will be set f
b060: 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65  or TEMP database
b070: 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72  s and their jour
b080: 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a  nals, transient.
b090: 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e  ** databases, an
b0a0: 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a  d subjournals..*
b0b0: 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
b0c0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
b0d0: 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73  ] flag is always
b0e0: 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63   used in conjunc
b0f0: 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
b100: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
b110: 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63  EATE] flag, whic
b120: 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63  h are both direc
b130: 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73  tly.** analogous
b140: 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61   to the O_EXCL a
b150: 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73  nd O_CREAT flags
b160: 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70   of the POSIX op
b170: 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68  en().** API.  Th
b180: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58  e SQLITE_OPEN_EX
b190: 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68  CLUSIVE flag, wh
b1a0: 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74  en paired with t
b1b0: 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50  he .** SQLITE_OP
b1c0: 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73  EN_CREATE, is us
b1d0: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
b1e0: 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  hat file should 
b1f0: 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65  always.** be cre
b200: 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69  ated, and that i
b210: 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66  t is an error if
b220: 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73   it already exis
b230: 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e  ts..** It is <i>
b240: 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20  not</i> used to 
b250: 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c  indicate the fil
b260: 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e  e should be open
b270: 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75  ed .** for exclu
b280: 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a  sive access..**.
b290: 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f  ** ^At least szO
b2a0: 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d  sFile bytes of m
b2b0: 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61  emory are alloca
b2c0: 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  ted by SQLite.**
b2d0: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73   to hold the  [s
b2e0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72  qlite3_file] str
b2f0: 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73  ucture passed as
b300: 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   the third.** ar
b310: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e  gument to xOpen.
b320: 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68    The xOpen meth
b330: 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  od does not have
b340: 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20   to.** allocate 
b350: 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69  the structure; i
b360: 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69  t should just fi
b370: 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20  ll it in.  Note 
b380: 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65  that.** the xOpe
b390: 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65  n method must se
b3a0: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
b3b0: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65  le.pMethods to e
b3c0: 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64  ither.** a valid
b3d0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
b3e0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20  hods] object or 
b3f0: 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20  to NULL.  xOpen 
b400: 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20  must do.** this 
b410: 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e  even if the open
b420: 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20   fails.  SQLite 
b430: 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65  expects that the
b440: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
b450: 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e  ethods.** elemen
b460: 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  t will be valid 
b470: 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75  after xOpen retu
b480: 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f  rns regardless o
b490: 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a  f the success.**
b4a0: 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74   or failure of t
b4b0: 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a  he xOpen call..*
b4c0: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
b4d0: 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20  fs.xAccess]].** 
b4e0: 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d  ^The flags argum
b4f0: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
b500: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
b510: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
b520: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
b530: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
b540: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
b550: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
b560: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
b570: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
b580: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
b590: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
b5a0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
b5b0: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
b5c0: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
b5d0: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
b5e0: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
b5f0: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
b600: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
b610: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
b620: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
b630: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
b640: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
b650: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
b660: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78  athname.  The ex
b670: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
b680: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
b690: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
b6a0: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
b6b0: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
b6c0: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
b6d0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
b6e0: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
b6f0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
b700: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
b710: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
b720: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
b730: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
b740: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
b750: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
b760: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
b770: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
b780: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
b790: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
b7a0: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
b7b0: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
b7c0: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
b7d0: 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74  leep(), xCurrent
b7e0: 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72  Time(), and xCur
b7f0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a  rentTimeInt64().
b800: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ** interfaces ar
b810: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
b820: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
b830: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
b840: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
b850: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
b860: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
b870: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
b880: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
b890: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
b8a0: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
b8b0: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
b8c0: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
b8d0: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
b8e0: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
b8f0: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
b900: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
b910: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
b920: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
b930: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
b940: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
b950: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
b960: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
b970: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
b980: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
b990: 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75  given.  ^The xCu
b9a0: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
b9b0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
b9c0: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
b9d0: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
b9e0: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  t date and time 
b9f0: 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67  as.** a floating
ba00: 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a   point value..**
ba10: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
ba20: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
ba30: 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20   returns, as an 
ba40: 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c  integer, the Jul
ba50: 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65  ian.** Day Numbe
ba60: 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20  r multiplied by 
ba70: 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75  86400000 (the nu
ba80: 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
ba90: 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34  onds in .** a 24
baa0: 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a  -hour day).  .**
bab0: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
bac0: 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69  e the xCurrentTi
bad0: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
bae0: 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72   to get the curr
baf0: 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20  ent.** date and 
bb00: 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74  time if that met
bb10: 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65  hod is available
bb20: 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73   (if iVersion is
bb30: 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65   2 or .** greate
bb40: 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69  r and the functi
bb50: 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
bb60: 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c  t NULL) and will
bb70: 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f   fall back.** to
bb80: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
bb90: 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  if xCurrentTimeI
bba0: 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69  nt64() is unavai
bbb0: 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lable..**.** ^Th
bbc0: 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  e xSetSystemCall
bbd0: 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61  (), xGetSystemCa
bbe0: 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53  ll(), and xNestS
bbf0: 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65  ystemCall() inte
bc00: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
bc10: 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51  t used by the SQ
bc20: 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73  Lite core.  Thes
bc30: 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72  e optional inter
bc40: 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
bc50: 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46  ed.** by some VF
bc60: 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74  Ses to facilitat
bc70: 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65  e testing of the
bc80: 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76   VFS code. By ov
bc90: 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73  erriding .** sys
bca0: 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66  tem calls with f
bcb0: 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69  unctions under i
bcc0: 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65  ts control, a te
bcd0: 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a  st program can.*
bce0: 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74  * simulate fault
bcf0: 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64  s and error cond
bd00: 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c  itions that woul
bd10: 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64  d otherwise be d
bd20: 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69  ifficult.** or i
bd30: 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64  mpossible to ind
bd40: 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66  uce.  The set of
bd50: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68   system calls th
bd60: 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  at can be overri
bd70: 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66  dden.** varies f
bd80: 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61  rom one VFS to a
bd90: 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d  nother, and from
bda0: 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20   one version of 
bdb0: 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20  the same VFS to 
bdc0: 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70  the.** next.  Ap
bdd0: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
bde0: 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66  use these interf
bdf0: 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65  aces must be pre
be00: 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a  pared for any.**
be10: 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65   or all of these
be20: 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62   interfaces to b
be30: 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68  e NULL or for th
be40: 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20  eir behavior to 
be50: 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f  change.** from o
be60: 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  ne release to th
be70: 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  e next.  Applica
be80: 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61  tions must not a
be90: 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73  ttempt to access
bea0: 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65  .** any of these
beb0: 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20   methods if the 
bec0: 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20  iVersion of the 
bed0: 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e  VFS is less than
bee0: 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73   3..*/.typedef s
bef0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
bf00: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74  s sqlite3_vfs;.t
bf10: 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
bf20: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
bf30: 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74  r)(void);.struct
bf40: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
bf50: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
bf60: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
bf70: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
bf80: 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79  umber (currently
bf90: 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f   3) */.  int szO
bfa0: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
bfb0: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
bfc0: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
bfd0: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
bfe0: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
bff0: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
c000: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
c010: 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
c020: 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
c030: 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
c040: 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
c050: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
c060: 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
c070: 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
c080: 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
c090: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
c0a0: 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
c0b0: 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
c0c0: 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
c0d0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
c0e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
c0f0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
c100: 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
c110: 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
c120: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
c130: 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
c140: 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
c150: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
c160: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
c170: 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
c180: 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
c190: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
c1a0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
c1b0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
c1c0: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
c1d0: 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28  *xFullPathname)(
c1e0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
c1f0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
c200: 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20   int nOut, char 
c210: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
c220: 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74  (*xDlOpen)(sqlit
c230: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
c240: 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b  har *zFilename);
c250: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72  .  void (*xDlErr
c260: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
c270: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
c280: 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76  r *zErrMsg);.  v
c290: 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28  oid (*(*xDlSym)(
c2a0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
c2b0: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
c2c0: 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b  zSymbol))(void);
c2d0: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
c2e0: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
c2f0: 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
c300: 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
c310: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
c320: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
c330: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
c340: 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
c350: 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
c360: 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
c370: 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
c380: 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
c390: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  *);.  int (*xGet
c3a0: 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74  LastError)(sqlit
c3b0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68  e3_vfs*, int, ch
c3c0: 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  ar *);.  /*.  **
c3d0: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
c3e0: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
c3f0: 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74  n 1 of the sqlit
c400: 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a  e_vfs object.  *
c410: 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  * definition.  T
c420: 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77  hose that follow
c430: 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65   are added in ve
c440: 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72  rsion 2 or later
c450: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43  .  */.  int (*xC
c460: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29  urrentTimeInt64)
c470: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73  (sqlite3_vfs*, s
c480: 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a  qlite3_int64*);.
c490: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
c4a0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
c4b0: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e  in versions 1 an
c4c0: 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74  d 2 of the sqlit
c4d0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
c4e0: 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61  ** Those below a
c4f0: 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  re for version 3
c500: 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20   and greater..  
c510: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53  */.  int (*xSetS
c520: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
c530: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
c540: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
c550: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
c560: 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63  ;.  sqlite3_sysc
c570: 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79  all_ptr (*xGetSy
c580: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
c590: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
c5a0: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f  ar *zName);.  co
c5b0: 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78  nst char *(*xNex
c5c0: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
c5d0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
c5e0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
c5f0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
c600: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
c610: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72  n versions 1 thr
c620: 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71  ough 3 of the sq
c630: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
c640: 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73  .  ** New fields
c650: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
c660: 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69   in figure versi
c670: 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69  ons.  The iVersi
c680: 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69  on.  ** value wi
c690: 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65  ll increment whe
c6a0: 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65  never this happe
c6b0: 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ns. .  */.};../*
c6c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
c6d0: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
c6e0: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ess VFS method.*
c6f0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
c700: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
c710: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
c720: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
c730: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
c740: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
c750: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
c760: 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72  ect.  They deter
c770: 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e  mine.** what kin
c780: 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73  d of permissions
c790: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
c7a0: 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66  hod is looking f
c7b0: 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  or..** With SQLI
c7c0: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
c7d0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
c7e0: 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63  thod.** simply c
c7f0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
c800: 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a  e file exists..*
c810: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
c820: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20  CESS_READWRITE, 
c830: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
c840: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
c850: 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64  ther the named d
c860: 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68  irectory is both
c870: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
c880: 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74  itable.** (in ot
c890: 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69  her words, if fi
c8a0: 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64  les can be added
c8b0: 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72  , removed, and r
c8c0: 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a  enamed within.**
c8d0: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e   the directory).
c8e0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41  .** The SQLITE_A
c8f0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
c900: 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72  constant is curr
c910: 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20  ently used only 
c920: 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f  by the.** [temp_
c930: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
c940: 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20  pragma], though 
c950: 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67  this could chang
c960: 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a  e in a future.**
c970: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
c980: 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  te..** With SQLI
c990: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20  TE_ACCESS_READ, 
c9a0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
c9b0: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
c9c0: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73  ther the file is
c9d0: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
c9e0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
c9f0: 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a  AD constant is.*
ca00: 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73  * currently unus
ca10: 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69  ed, though it mi
ca20: 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61  ght be used in a
ca30: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
ca40: 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f  of.** SQLite..*/
ca50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ca60: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
ca70: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
ca80: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
ca90: 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62  TE 1   /* Used b
caa0: 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74  y PRAGMA temp_st
cab0: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f  ore_directory */
cac0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cad0: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
cae0: 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a   2   /* Unused *
caf0: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
cb00: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
cb10: 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65   xShmLock VFS me
cb20: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
cb30: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
cb40: 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61  ts define the va
cb50: 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70  rious locking op
cb60: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f  erations.** allo
cb70: 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c  wed by the xShmL
cb80: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73  ock method of [s
cb90: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
cba0: 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c  s].  The.** foll
cbb0: 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e  owing are the on
cbc0: 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61  ly legal combina
cbd0: 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74  tions of flags t
cbe0: 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63  o the.** xShmLoc
cbf0: 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  k method:.**.** 
cc00: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  <ul>.** <li>  SQ
cc10: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
cc20: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
cc30: 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
cc40: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
cc50: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
cc60: 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  E.** <li>  SQLIT
cc70: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
cc80: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
cc90: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
cca0: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
ccb0: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
ccc0: 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VE.** </ul>.**.*
ccd0: 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67  * When unlocking
cce0: 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45  , the same SHARE
ccf0: 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66  D or EXCLUSIVE f
cd00: 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70  lag must be supp
cd10: 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67  lied as.** was g
cd20: 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72  iven no the corr
cd30: 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20  esponding lock. 
cd40: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d   .**.** The xShm
cd50: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20  Lock method can 
cd60: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
cd70: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
cd80: 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74  SHARED or.** bet
cd90: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
cda0: 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74  d EXCLUSIVE.  It
cdb0: 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69   cannot transiti
cdc0: 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45  on between SHARE
cdd0: 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49  D.** and EXCLUSI
cde0: 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  VE..*/.#define S
cdf0: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
ce00: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
ce10: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
ce20: 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
ce30: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48  ne SQLITE_SHM_SH
ce40: 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65  ARED       4.#de
ce50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
ce60: 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a  EXCLUSIVE    8..
ce70: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ce80: 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b  Maximum xShmLock
ce90: 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65   index.**.** The
cea0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
ceb0: 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   on [sqlite3_io_
cec0: 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65  methods] may use
ced0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
cee0: 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70  en 0 and this up
cef0: 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73  per bound as its
cf00: 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65   "offset" argume
cf10: 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  nt..** The SQLit
cf20: 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65  e core will neve
cf30: 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71  r attempt to acq
cf40: 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20  uire or release 
cf50: 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64  a.** lock outsid
cf60: 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a  e of this range.
cf70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
cf80: 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20  E_SHM_NLOCK     
cf90: 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     8.../*.** CAP
cfa0: 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a  I3REF: Initializ
cfb0: 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  e The SQLite Lib
cfc0: 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rary.**.** ^The 
cfd0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
cfe0: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
cff0: 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
d000: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
d010: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68   ^The sqlite3_sh
d020: 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65  utdown() routine
d030: 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  .** deallocates 
d040: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68  any resources th
d050: 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65  at were allocate
d060: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  d by sqlite3_ini
d070: 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68  tialize()..** Th
d080: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
d090: 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64   designed to aid
d0a0: 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74   in process init
d0b0: 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a  ialization and.*
d0c0: 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d  * shutdown on em
d0d0: 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20  bedded systems. 
d0e0: 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70   Workstation app
d0f0: 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a  lications using.
d100: 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c  ** SQLite normal
d110: 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ly do not need t
d120: 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  o invoke either 
d130: 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
d140: 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  s..**.** A call 
d150: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
d160: 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65  alize() is an "e
d170: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
d180: 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66  f it is.** the f
d190: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
d1a0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
d1b0: 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67  s invoked during
d1c0: 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
d1d0: 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c  .** the process,
d1e0: 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65   or if it is the
d1f0: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
d200: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d210: 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66   is invoked.** f
d220: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20  ollowing a call 
d230: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
d240: 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61  own().  ^(Only a
d250: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
d260: 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69  .** of sqlite3_i
d270: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73  nitialize() does
d280: 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74   any initializat
d290: 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ion.  All other 
d2a0: 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72  calls.** are har
d2b0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
d2c0: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
d2d0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d2e0: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
d2f0: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
d300: 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
d310: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
d320: 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65  shutdown() since
d330: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
d340: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20  3_initialize(). 
d350: 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66   ^(Only.** an ef
d360: 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20  fective call to 
d370: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d380: 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e  () does any dein
d390: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  itialization..**
d3a0: 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64   All other valid
d3b0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
d3c0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65  3_shutdown() are
d3d0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
d3e0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  .)^.**.** The sq
d3f0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
d400: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
d410: 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20  threadsafe, but 
d420: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d430: 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54  ().** is not.  T
d440: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
d450: 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  own() interface 
d460: 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c  must only be cal
d470: 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69  led from a.** si
d480: 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c  ngle thread.  Al
d490: 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  l open [database
d4a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75   connections] mu
d4b0: 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64  st be closed and
d4c0: 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51   all.** other SQ
d4d0: 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d  Lite resources m
d4e0: 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  ust be deallocat
d4f0: 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f  ed prior to invo
d500: 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  king.** sqlite3_
d510: 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a  shutdown()..**.*
d520: 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68  * Among other th
d530: 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69  ings, ^sqlite3_i
d540: 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c  nitialize() will
d550: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
d560: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53  e3_os_init().  S
d570: 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74  imilarly, ^sqlit
d580: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
d590: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c   will invoke sql
d5a0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a  ite3_os_end()..*
d5b0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
d5c0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
d5d0: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
d5e0: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
d5f0: 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f  ccess..** ^If fo
d600: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73  r some reason, s
d610: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
d620: 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  e() is unable to
d630: 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74   initialize.** t
d640: 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68  he library (perh
d650: 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65  aps it is unable
d660: 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e   to allocate a n
d670: 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73  eeded resource s
d680: 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65  uch.** as a mute
d690: 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e  x) it returns an
d6a0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74   [error code] ot
d6b0: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
d6c0: 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _OK]..**.** ^The
d6d0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
d6e0: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
d6f0: 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
d700: 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
d710: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
d720: 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
d730: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
d740: 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
d750: 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
d760: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
d770: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
d780: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
d790: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
d7a0: 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
d7b0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
d7c0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
d7d0: 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
d7e0: 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
d7f0: 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
d800: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
d810: 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
d820: 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
d830: 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
d840: 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51   ^However, if SQ
d850: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
d860: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
d870: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
d880: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
d890: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
d8a0: 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
d8b0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
d8c0: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
d8d0: 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
d8e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
d8f0: 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
d900: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
d910: 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
d920: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
d930: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
d940: 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
d950: 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
d960: 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
d970: 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
d980: 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
d990: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
d9a0: 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
d9b0: 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
d9c0: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
d9d0: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
d9e0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
d9f0: 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
da00: 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
da10: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
da20: 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
da30: 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
da40: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
da50: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d   with [SQLITE_OM
da60: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67  IT_AUTOINIT] mig
da70: 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a  ht become the.**
da80: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
da90: 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  r in some future
daa0: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
dab0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te..**.** The sq
dac0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
dad0: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65  routine does ope
dae0: 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
daf0: 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61  ecific.** initia
db00: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  lization of the 
db10: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
db20: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
db30: 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  end().** routine
db40: 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
db50: 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  ct of sqlite3_os
db60: 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61  _init().  Typica
db70: 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f  l tasks.** perfo
db80: 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f  rmed by these ro
db90: 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61  utines include a
dba0: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61  llocation or dea
dbb0: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
dbc0: 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73  static resources
dbd0: 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  , initialization
dbe0: 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61   of global varia
dbf0: 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67  bles,.** setting
dc00: 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73   up a default [s
dc10: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75  qlite3_vfs] modu
dc20: 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75  le, or setting u
dc30: 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63  p.** a default c
dc40: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69  onfiguration usi
dc50: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ng [sqlite3_conf
dc60: 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ig()]..**.** The
dc70: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
dc80: 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  uld never invoke
dc90: 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
dca0: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20  os_init().** or 
dcb0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
dcc0: 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20   directly.  The 
dcd0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
dce0: 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a  ld only invoke.*
dcf0: 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
dd00: 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lize() and sqlit
dd10: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
dd20: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
dd30: 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  nit().** interfa
dd40: 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74  ce is called aut
dd50: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
dd60: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
dd70: 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  () and.** sqlite
dd80: 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
dd90: 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
dda0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
ddb0: 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
ddc0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
ddd0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
dde0: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
ddf0: 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
de00: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
de10: 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
de20: 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69  led for Unix, Wi
de30: 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a  ndows, or OS/2..
de40: 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20  ** When [custom 
de50: 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66  builds | built f
de60: 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72  or other platfor
de70: 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68  ms].** (using th
de80: 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48  e [SQLITE_OS_OTH
de90: 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ER=1] compile-ti
dea0: 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
deb0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
dec0: 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
ded0: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
dee0: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
def0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
df00: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
df10: 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
df20: 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
df30: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
df40: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
df50: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
df60: 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
df70: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
df80: 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
df90: 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
dfa0: 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
dfb0: 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74   failure..*/.int
dfc0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
dfd0: 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ize(void);.int s
dfe0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
dff0: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
e000: 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
e010: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
e020: 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
e030: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
e040: 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
e050: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
e060: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
e070: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
e080: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
e090: 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
e0a0: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
e0b0: 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
e0c0: 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
e0d0: 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
e0e0: 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
e0f0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
e100: 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
e110: 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
e120: 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
e130: 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
e140: 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
e150: 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
e160: 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
e170: 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
e180: 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
e190: 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
e1a0: 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
e1b0: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  eds..**.** The s
e1c0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
e1d0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
e1e0: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
e1f0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
e200: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
e210: 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
e220: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
e230: 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
e240: 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
e250: 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
e260: 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  g() is running. 
e270: 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71   Furthermore, sq
e280: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a  lite3_config().*
e290: 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
e2a0: 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
e2b0: 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
e2c0: 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
e2d0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e2e0: 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
e2f0: 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
e300: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
e310: 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
e320: 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c  config() is call
e330: 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
e340: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
e350: 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73  and before.** [s
e360: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
e370: 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20  )] then it will 
e380: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
e390: 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  SUSE..** Note, h
e3a0: 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71  owever, that ^sq
e3b0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
e3c0: 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
e3d0: 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
e3e0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
e3f0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
e400: 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
e410: 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
e420: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
e430: 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
e440: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
e450: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66  integer.** [conf
e460: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
e470: 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
e480: 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
e490: 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
e4a0: 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
e4b0: 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
e4c0: 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
e4d0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
e4e0: 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
e4f0: 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
e500: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
e510: 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ..**.** ^When a 
e520: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
e530: 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
e540: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
e550: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
e560: 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70  ]..** ^If the op
e570: 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
e580: 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
e590: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
e5a0: 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68  ption.** then th
e5b0: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
e5c0: 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
e5d0: 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69  rror code]..*/.i
e5e0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  nt sqlite3_confi
e5f0: 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  g(int, ...);../*
e600: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
e610: 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65  nfigure database
e620: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a   connections.**.
e630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
e640: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
e650: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
e660: 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
e670: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
e680: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
e690: 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
e6a0: 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
e6b0: 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
e6c0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
e6d0: 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
e6e0: 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
e6f0: 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
e700: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
e710: 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
e720: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
e730: 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  )..**.** The sec
e740: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
e750: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
e760: 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
e770: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42  he.** [SQLITE_DB
e780: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
e790: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
e7a0: 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65   verb] - an inte
e7b0: 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61  ger code .** tha
e7c0: 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
e7d0: 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
e7e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
e7f0: 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
e800: 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62  nfigured..** Sub
e810: 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
e820: 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  s vary depending
e830: 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72   on the configur
e840: 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a  ation verb..**.*
e850: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
e860: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
e870: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
e880: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
e890: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
e8a0: 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
e8b0: 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
e8c0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
e8d0: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
e8e0: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
e8f0: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
e900: 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
e910: 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
e920: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
e930: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
e940: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
e950: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
e960: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
e970: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
e980: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
e990: 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
e9a0: 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
e9b0: 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
e9c0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
e9d0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
e9e0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
e9f0: 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
ea00: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
ea10: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
ea20: 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
ea30: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
ea40: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
ea50: 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
ea60: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
ea70: 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
ea80: 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
ea90: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
eaa0: 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
eab0: 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
eac0: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
ead0: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
eae0: 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
eaf0: 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
eb00: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
eb10: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
eb20: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
eb30: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
eb40: 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
eb50: 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
eb60: 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
eb70: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
eb80: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
eb90: 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
eba0: 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
ebb0: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
ebc0: 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
ebd0: 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
ebe0: 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
ebf0: 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
ec00: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
ec10: 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
ec20: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
ec30: 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
ec40: 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
ec50: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
ec60: 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
ec70: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
ec80: 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
ec90: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
eca0: 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
ecb0: 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
ecc0: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
ecd0: 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
ece0: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
ecf0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
ed00: 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
ed10: 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
ed20: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
ed30: 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
ed40: 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
ed50: 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
ed60: 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
ed70: 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
ed80: 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52   The xMalloc, xR
ed90: 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65  ealloc, and xFre
eda0: 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
edb0: 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
edc0: 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
edd0: 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
ede0: 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
edf0: 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
ee00: 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  rary..** ^SQLite
ee10: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
ee20: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
ee30: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
ee40: 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
ee50: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
ee60: 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
ee70: 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a  o xRoundup..**.*
ee80: 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
ee90: 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
eea0: 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
eeb0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
eec0: 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
eed0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
eee0: 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
eef0: 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
ef00: 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
ef10: 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
ef20: 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
ef30: 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
ef40: 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
ef50: 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
ef60: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
ef70: 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
ef80: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
ef90: 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
efa0: 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
efb0: 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
efc0: 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
efd0: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
efe0: 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
eff0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
f000: 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
f010: 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
f020: 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
f030: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
f040: 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
f050: 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
f060: 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45  power of 2..** E
f070: 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
f080: 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63  cation request c
f090: 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68  oming in through
f0a0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
f0b0: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
f0c0: 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69  e3_realloc()] fi
f0d0: 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64  rst calls xRound
f0e0: 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70  up.  If xRoundup
f0f0: 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20   returns 0, .** 
f100: 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20  that causes the 
f110: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65  corresponding me
f120: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
f130: 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54  to fail..**.** T
f140: 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
f150: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
f160: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
f170: 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .  (For example,
f180: 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c  .** it might all
f190: 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72  ocate any requir
f1a0: 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69  e mutexes or ini
f1b0: 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c  tialize internal
f1c0: 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75   data.** structu
f1d0: 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64  res.  The xShutd
f1e0: 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  own method is in
f1f0: 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c  voked (indirectl
f200: 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  y) by.** [sqlite
f210: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e  3_shutdown()] an
f220: 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63  d should dealloc
f230: 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65  ate any resource
f240: 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79  s acquired.** by
f250: 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70   xInit.  The pAp
f260: 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73  pData pointer is
f270: 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c   used as the onl
f280: 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  y parameter to.*
f290: 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75  * xInit and xShu
f2a0: 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  tdown..**.** SQL
f2b0: 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  ite holds the [S
f2c0: 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
f2d0: 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78  IC_MASTER] mutex
f2e0: 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73   when it invokes
f2f0: 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65  .** the xInit me
f300: 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e  thod, so the xIn
f310: 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e  it method need n
f320: 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  ot be threadsafe
f330: 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64  .  The.** xShutd
f340: 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e  own method is on
f350: 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b  ly called from [
f360: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f370: 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a  ()] so it does.*
f380: 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  * not need to be
f390: 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68   threadsafe eith
f3a0: 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68  er.  For all oth
f3b0: 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69  er methods, SQLi
f3c0: 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20  te.** holds the 
f3d0: 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
f3e0: 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20  ATIC_MEM] mutex 
f3f0: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a  as long as the.*
f400: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
f410: 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66  _MEMSTATUS] conf
f420: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
f430: 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77   is turned on (w
f440: 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79  hich.** it is by
f450: 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f   default) and so
f460: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65   the methods are
f470: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73   automatically s
f480: 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f  erialized..** Ho
f490: 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54  wever, if [SQLIT
f4a0: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
f4b0: 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c  US] is disabled,
f4c0: 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a   then the other.
f4d0: 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ** methods must 
f4e0: 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72  be threadsafe or
f4f0: 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72   else make their
f500: 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74   own arrangement
f510: 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69  s for.** seriali
f520: 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  zation..**.** SQ
f530: 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
f540: 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d  invoke xInit() m
f550: 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69  ore than once wi
f560: 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65  thout an interve
f570: 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  ning.** call to 
f580: 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a  xShutdown()..*/.
f590: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
f5a0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
f5b0: 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ds sqlite3_mem_m
f5c0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
f5d0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
f5e0: 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ds {.  void *(*x
f5f0: 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20  Malloc)(int);   
f600: 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20        /* Memory 
f610: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
f620: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ion */.  void (*
f630: 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20  xFree)(void*);  
f640: 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20          /* Free 
f650: 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  a prior allocati
f660: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  on */.  void *(*
f670: 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c  xRealloc)(void*,
f680: 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65  int);  /* Resize
f690: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
f6a0: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29  /.  int (*xSize)
f6b0: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
f6c0: 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65     /* Return the
f6d0: 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f   size of an allo
f6e0: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
f6f0: 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29  (*xRoundup)(int)
f700: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f  ;          /* Ro
f710: 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73  und up request s
f720: 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f  ize to allocatio
f730: 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20  n size */.  int 
f740: 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b  (*xInit)(void*);
f750: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e             /* In
f760: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
f770: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
f780: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64  .  void (*xShutd
f790: 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  own)(void*);    
f7a0: 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a    /* Deinitializ
f7b0: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
f7c0: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
f7d0: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
f7e0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72             /* Ar
f7f0: 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28  gument to xInit(
f800: 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28  ) and xShutdown(
f810: 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ) */.};../*.** C
f820: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
f830: 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
f840: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e  * KEYWORDS: {con
f850: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
f860: 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  n}.**.** These c
f870: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
f880: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
f890: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
f8a0: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
f8b0: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
f8c0: 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
f8d0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
f8e0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
f8f0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
f900: 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
f910: 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
f920: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
f930: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
f940: 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
f950: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
f960: 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
f970: 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
f980: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
f990: 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
f9a0: 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
f9b0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
f9c0: 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
f9d0: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
f9e0: 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
f9f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
fa00: 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
fa10: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
fa20: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
fa30: 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
fa40: 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
fa50: 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
fa60: 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
fa70: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
fa80: 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  l>.** [[SQLITE_C
fa90: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
faa0: 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
fab0: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
fac0: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
fad0: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
fae0: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
faf0: 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
fb00: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
fb10: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
fb20: 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
fb30: 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
fb40: 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
fb50: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
fb60: 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
fb70: 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
fb80: 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
fb90: 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
fba0: 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20  ingle thread.   
fbb0: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
fbc0: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
fbd0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
fbe0: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
fbf0: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
fc00: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
fc10: 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
fc20: 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
fc30: 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61  hange the [threa
fc40: 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20  ding mode] from 
fc50: 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76  its default.** v
fc60: 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74  alue of Single-t
fc70: 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71  hread and so [sq
fc80: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
fc90: 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20  will return .** 
fca0: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
fcb0: 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
fcc0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
fcd0: 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20  SINGLETHREAD.** 
fce0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
fcf0: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
fd00: 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
fd10: 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c  _MULTITHREAD]] <
fd20: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
fd30: 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74  _MULTITHREAD</dt
fd40: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
fd50: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
fd60: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
fd70: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
fd80: 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
fd90: 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75  ding mode] to Mu
fda0: 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  lti-thread.  In 
fdb0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
fdc0: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
fdd0: 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
fde0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
fdf0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
fe00: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
fe10: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
fe20: 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
fe30: 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
fe40: 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
fe50: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
fe60: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
fe70: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
fe80: 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
fe90: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
fea0: 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
feb0: 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
fec0: 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
fed0: 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
fee0: 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
fef0: 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
ff00: 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
ff10: 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
ff20: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
ff30: 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
ff40: 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74  time.  ^If SQLit
ff50: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
ff60: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
ff70: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
ff80: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
ff90: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
ffa0: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
ffb0: 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
ffc0: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75  le to set the Mu
ffd0: 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
ffe0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
fff0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
10000 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
10010 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
10020 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
10030 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
10040 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
10050 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10060 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
10070 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
10080 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c  G_SERIALIZED]] <
10090 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
100a0 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e  _SERIALIZED</dt>
100b0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
100c0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
100d0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
100e0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
100f0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
10100 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
10110 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65  ialized. In othe
10120 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70  r words, this op
10130 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
10140 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
10150 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
10160 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
10170 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
10180 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
10190 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
101a0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
101b0 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
101c0 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
101d0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
101e0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
101f0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
10200 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
10210 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
10220 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
10230 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
10240 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10250 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
10260 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
10270 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
10280 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
10290 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
102a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
102b0 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
102c0 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
102d0 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
102e0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
102f0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
10300 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
10310 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
10320 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
10330 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
10340 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
10350 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
10360 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
10370 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
10380 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69   to set the Seri
10390 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
103a0 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
103b0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
103c0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
103d0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
103e0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
103f0 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
10400 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66  _SERIALIZED conf
10410 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10420 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
10430 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
10440 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
10450 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f  _CONFIG_MALLOC</
10460 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
10470 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
10480 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
10490 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
104a0 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
104b0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
104c0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
104d0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
104e0 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
104f0 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
10500 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
10510 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10520 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  n routines to be
10530 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f   used in place o
10540 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  f.** the memory 
10550 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
10560 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
10570 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65  QLite.)^ ^SQLite
10580 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77   makes.** its ow
10590 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
105a0 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  f the content of
105b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
105c0 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
105d0 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74  ture.** before t
105e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
105f0 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72  ig()] call retur
10600 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ns.</dd>.**.** [
10610 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
10620 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  ETMALLOC]] <dt>S
10630 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
10640 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
10650 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
10660 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
10670 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
10680 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
10690 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
106a0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
106b0 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
106c0 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c  cture.  The [sql
106d0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
106e0 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
106f0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
10700 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
10710 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
10720 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29  ation routines.)
10730 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
10740 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
10750 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
10760 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
10770 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
10780 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
10790 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
107a0 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
107b0 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
107c0 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
107d0 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
107e0 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ple. </dd>.**.**
107f0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
10800 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74  _MEMSTATUS]] <dt
10810 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
10820 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a  EMSTATUS</dt>.**
10830 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
10840 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20  on takes single 
10850 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
10860 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65   int, interprete
10870 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65  d as a .** boole
10880 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65  an, which enable
10890 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
108a0 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20  e collection of 
108b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
108c0 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73  n .** statistics
108d0 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20  . ^(When memory 
108e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
108f0 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
10900 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c  ed, the .** foll
10910 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
10920 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e  erfaces become n
10930 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a  on-operational:.
10940 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  **   <ul>.**   <
10950 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
10960 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20  ory_used()].**  
10970 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
10980 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
10990 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
109a0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
109b0 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20  limit64()].**   
109c0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
109d0 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75  atus()].**   </u
109e0 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20  l>)^.** ^Memory 
109f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
10a00 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65  stics are enable
10a10 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c  d by default unl
10a20 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  ess SQLite is.**
10a30 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
10a40 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d  SQLITE_DEFAULT_M
10a50 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77  EMSTATUS]=0 in w
10a60 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79  hich case memory
10a70 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  .** allocation s
10a80 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
10a90 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
10aa0 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  t..** </dd>.**.*
10ab0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
10ac0 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e  G_SCRATCH]] <dt>
10ad0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
10ae0 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RATCH</dt>.** <d
10af0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
10b00 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
10b10 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
10b20 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
10b30 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61   use for.** scra
10b40 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65  tch memory.  The
10b50 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
10b60 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74  uments:  A point
10b70 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  er an 8-byte.** 
10b80 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62  aligned memory b
10b90 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68  uffer from which
10ba0 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c   the scratch all
10bb0 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65  ocations will be
10bc0 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73  .** drawn, the s
10bd0 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61  ize of each scra
10be0 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28  tch allocation (
10bf0 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20  sz),.** and the 
10c00 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
10c10 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  f scratch alloca
10c20 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20  tions (N).  The 
10c30 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d  sz.** argument m
10c40 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c  ust be a multipl
10c50 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20  e of 16..** The 
10c60 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
10c70 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72  ust be a pointer
10c80 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c   to an 8-byte al
10c90 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20  igned buffer.** 
10ca0 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
10cb0 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
10cc0 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
10cd0 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68  l use no more th
10ce0 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62  an two scratch b
10cf0 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61  uffers per threa
10d00 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75  d.  So.** N shou
10d10 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69  ld be set to twi
10d20 63 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20  ce the expected 
10d30 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
10d40 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53  f threads..** ^S
10d50 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
10d60 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74   require a scrat
10d70 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69  ch buffer that i
10d80 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a  s more than 6.**
10d90 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62   times the datab
10da0 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e  ase page size. ^
10db0 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20  If SQLite needs 
10dc0 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c  needs additional
10dd0 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
10de0 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ry beyond what i
10df0 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
10e00 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
10e10 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a   option, then .*
10e20 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
10e30 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65  c()] will be use
10e40 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  d to obtain the 
10e50 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f  memory needed.</
10e60 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
10e70 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
10e80 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CHE]] <dt>SQLITE
10e90 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
10ea0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
10eb0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
10ec0 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
10ed0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
10ee0 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
10ef0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61   for.** the data
10f00 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20  base page cache 
10f10 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74  with the default
10f20 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
10f30 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a  ementation.  .**
10f40 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   This configurat
10f50 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  ion should not b
10f60 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70  e used if an app
10f70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20  lication-define 
10f80 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
10f90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
10fa0 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65  loaded using the
10fb0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
10fc0 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a  CACHE2 option..*
10fd0 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
10fe0 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  e arguments to t
10ff0 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f  his option: A po
11000 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20  inter to 8-byte 
11010 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72  aligned.** memor
11020 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  y, the size of e
11030 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20  ach page buffer 
11040 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75  (sz), and the nu
11050 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e  mber of pages (N
11060 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67  )..** The sz arg
11070 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
11080 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
11090 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65  largest database
110a0 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65   page.** (a powe
110b0 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e  r of two between
110c0 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20   512 and 32768) 
110d0 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78  plus a little ex
110e0 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  tra for each.** 
110f0 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54  page header.  ^T
11100 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73  he page header s
11110 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20  ize is 20 to 40 
11120 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20  bytes depending 
11130 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61  on.** the host a
11140 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49  rchitecture.  ^I
11150 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
11160 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
11170 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
11180 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74  to make sz a lit
11190 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20  tle too large.  
111a0 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
111b0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
111c0 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74  nt to an allocat
111d0 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ion of at least 
111e0 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
111f0 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
11200 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65   will use the me
11210 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79  mory provided by
11220 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
11230 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69  ent to satisfy i
11240 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65  ts.** memory nee
11250 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  ds for the first
11260 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74   N pages that it
11270 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20   adds to cache. 
11280 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a   ^If additional.
11290 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  ** page cache me
112a0 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62  mory is needed b
112b0 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
112c0 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f  ovided by this o
112d0 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53  ption, then.** S
112e0 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73  QLite goes to [s
112f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
11300 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f   for the additio
11310 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63  nal storage spac
11320 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  e..** The pointe
11330 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
11340 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20  rgument must.** 
11350 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
11360 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
11370 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
11380 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
11390 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64  e.** will be und
113a0 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  efined.</dd>.**.
113b0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
113c0 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51  IG_HEAP]] <dt>SQ
113d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
113e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
113f0 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
11400 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
11410 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
11420 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
11430 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  .** for all of i
11440 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
11450 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
11460 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ds beyond those 
11470 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20  provided.** for 
11480 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
11490 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b  G_SCRATCH] and [
114a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
114b0 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65  GECACHE]..** The
114c0 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
114d0 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74  uments: An 8-byt
114e0 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65  e aligned pointe
114f0 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
11500 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
11510 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  f bytes in the m
11520 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
11530 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
11540 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a  location size..*
11550 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20  * ^If the first 
11560 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
11570 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
11580 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
11590 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
115a0 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
115b0 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
115c0 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
115d0 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
115e0 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
115f0 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
11600 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
11610 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
11620 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  C].  ^If the.** 
11630 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
11640 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65  s not NULL and e
11650 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
11660 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
11670 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
11680 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20  LE_MEMSYS5] are 
11690 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68  defined, then th
116a0 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
116b0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
116c0 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
116d0 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
116e0 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
116f0 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
11700 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
11710 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
11720 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
11730 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
11740 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
11750 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
11760 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
11770 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
11780 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
11790 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
117a0 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
117b0 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61  t 2**12. Reasona
117c0 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f  ble values.** fo
117d0 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  r the minimum al
117e0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72  location size ar
117f0 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32  e 2**5 through 2
11800 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  **8.</dd>.**.** 
11810 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11820 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
11830 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
11840 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
11850 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
11860 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
11870 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
11880 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
11890 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
118a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
118b0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
118c0 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
118d0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
118e0 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
118f0 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  el mutex routine
11900 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
11910 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74  place.** the mut
11920 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  ex routines buil
11930 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
11940 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
11950 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
11960 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
11970 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
11980 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
11990 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c  e before the cal
119a0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
119b0 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72  _config()] retur
119c0 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69  ns. ^If SQLite i
119d0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
119e0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
119f0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
11a00 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
11a10 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
11a20 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
11a30 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
11a40 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
11a50 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
11a60 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
11a70 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
11a80 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
11a90 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
11aa0 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69  NFIG_MUTEX confi
11ab0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
11ac0 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
11ad0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
11ae0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
11af0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
11b00 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
11b10 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
11b20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
11b30 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
11b40 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
11b50 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
11b60 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
11b70 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
11b80 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
11b90 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
11ba0 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
11bb0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
11bc0 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
11bd0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
11be0 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
11bf0 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
11c00 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
11c10 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
11c20 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
11c30 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
11c40 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
11c50 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
11c60 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
11c70 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
11c80 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
11c90 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
11ca0 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
11cb0 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
11cc0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11cd0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
11ce0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
11cf0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11d00 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
11d10 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
11d20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
11d30 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
11d40 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
11d50 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
11d60 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
11d70 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
11d80 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
11d90 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
11da0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11db0 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
11dc0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
11dd0 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
11de0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11df0 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e  LOOKASIDE]] <dt>
11e00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
11e10 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
11e20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
11e30 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
11e40 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
11e50 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c  rmine the defaul
11e60 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t.** memory allo
11e70 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c  cation for the l
11e80 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
11e90 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63  allocator on eac
11ea0 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
11eb0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
11ec0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
11ed0 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
11ee0 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
11ef0 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
11f00 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
11f10 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
11f20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
11f30 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
11f40 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20   connection.)^  
11f50 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65  ^(This option se
11f60 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66  ts the.** <i>def
11f70 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
11f80 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
11f90 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
11fa0 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62  OKASIDE].** verb
11fb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
11fc0 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
11fd0 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
11fe0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
11ff0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12000 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
12010 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
12020 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12030 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
12040 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12050 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e  FIG_PCACHE2</dt>
12060 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
12070 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
12080 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
12090 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
120a0 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69  r to.** an [sqli
120b0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
120c0 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  ds2] object.  Th
120d0 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  is object specif
120e0 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ies the interfac
120f0 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d  e.** to a custom
12100 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
12110 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e  ementation.)^  ^
12120 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
12130 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62  opy of the.** ob
12140 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74  ject and uses it
12150 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20   for page cache 
12160 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12170 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ns.</dd>.**.** [
12180 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
12190 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  ETPCACHE2]] <dt>
121a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
121b0 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  TPCACHE2</dt>.**
121c0 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
121d0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
121e0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
121f0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
12200 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
12210 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
12220 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74  ] object.  SQLit
12230 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20  e copies of the 
12240 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20  current.** page 
12250 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
12260 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f  tion into that o
12270 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  bject.)^ </dd>.*
12280 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12290 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53  NFIG_LOG]] <dt>S
122a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
122b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
122c0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
122d0 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _LOG option take
122e0 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a  s two arguments:
122f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
12300 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ** function with
12310 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72   a call signatur
12320 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69  e of void(*)(voi
12330 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
12340 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70  r*), .** and a p
12350 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20  ointer to void. 
12360 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
12370 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
12380 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69  NULL, it is.** i
12390 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74  nvoked by [sqlit
123a0 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f  e3_log()] to pro
123b0 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e  cess each loggin
123c0 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
123d0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f  e.** function po
123e0 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74  inter is NULL, t
123f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  he [sqlite3_log(
12400 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63  )] interface bec
12410 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a  omes a no-op..**
12420 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74   ^The void point
12430 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73  er that is the s
12440 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
12450 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
12460 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64  LOG is.** passed
12470 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
12480 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
12490 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
124a0 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
124b0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68  r.** function wh
124c0 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63  enever that func
124d0 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
124e0 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61    ^The second pa
124f0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
12500 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
12510 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  n is a copy of t
12520 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
12530 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  er to the corres
12540 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  ponding.** [sqli
12550 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20  te3_log()] call 
12560 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20  and is intended 
12570 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20  to be a [result 
12580 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
12590 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
125a0 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69  code].  ^The thi
125b0 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  rd parameter pas
125c0 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65  sed to the logge
125d0 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73  r is.** log mess
125e0 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74  age after format
125f0 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65  ting via [sqlite
12600 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a  3_snprintf()]..*
12610 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67  * The SQLite log
12620 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69  ging interface i
12630 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b  s not reentrant;
12640 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
12650 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
12660 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
12670 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76  ion must not inv
12680 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  oke any SQLite i
12690 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20  nterface..** In 
126a0 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
126b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
126c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
126d0 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
126e0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
126f0 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64   threadsafe. </d
12700 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12710 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c  E_CONFIG_URI]] <
12720 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12730 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69  _URI.** <dd> Thi
12740 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
12750 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
12760 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66   of type int. If
12770 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a   non-zero, then.
12780 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  ** URI handling 
12790 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62  is globally enab
127a0 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61  led. If the para
127b0 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74  meter is zero, t
127c0 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
127d0 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  .** is globally 
127e0 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52 49  disabled. If URI
127f0 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
12800 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61  bally enabled, a
12810 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20  ll filenames.** 
12820 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
12830 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
12840 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
12850 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
12860 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66  ()] or.** specif
12870 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ied as part of [
12880 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73  ATTACH] commands
12890 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
128a0 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64   as URIs, regard
128b0 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68  less.** of wheth
128c0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53  er or not the [S
128d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
128e0 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
128f0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
12900 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
12910 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73 20  pened. If it is 
12920 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
12930 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  d, filenames are
12940 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72  .** only interpr
12950 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20  eted as URIs if 
12960 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
12970 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20  URI flag is set 
12980 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61  when the.** data
12990 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
129a0 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64 65  is opened. By de
129b0 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c  fault, URI handl
129c0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
129d0 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65  ** disabled. The
129e0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d   default value m
129f0 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ay be changed by
12a00 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20   compiling with 
12a10 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  the.** [SQLITE_U
12a20 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64  SE_URI] symbol d
12a30 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  efined..**.** [[
12a40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
12a50 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f  ACHE]] [[SQLITE_
12a60 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
12a70 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
12a80 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61  _CONFIG_PCACHE a
12a90 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 4e 49  nd SQLITE_CONFNI
12aa0 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c  G_GETPCACHE.** <
12ab0 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  dd> These option
12ac0 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61  s are obsolete a
12ad0 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  nd should not be
12ae0 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64   used by new cod
12af0 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72  e..** They are r
12b00 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b  etained for back
12b10 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
12b20 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20  ity but are now 
12b30 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e  no-ops..** </dl>
12b40 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
12b50 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
12b60 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69  THREAD  1  /* ni
12b70 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
12b80 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
12b90 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e  THREAD   2  /* n
12ba0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
12bb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
12bc0 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20  ALIZED    3  /* 
12bd0 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
12be0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
12bf0 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a  LOC        4  /*
12c00 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
12c10 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
12c20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
12c30 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20  ETMALLOC     5  
12c40 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
12c50 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
12c60 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
12c70 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36  _SCRATCH       6
12c80 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
12c90 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
12ca0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
12cb0 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20  IG_PAGECACHE    
12cc0 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   7  /* void*, in
12cd0 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
12ce0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
12cf0 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20  NFIG_HEAP       
12d00 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     8  /* void*, 
12d10 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d  int nByte, int m
12d20 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  in */.#define SQ
12d30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
12d40 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20  TATUS     9  /* 
12d50 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69  boolean */.#defi
12d60 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
12d70 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30  _MUTEX        10
12d80 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
12d90 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  ex_methods* */.#
12da0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
12db0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20  NFIG_GETMUTEX   
12dc0 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33    11  /* sqlite3
12dd0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
12de0 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79  */./* previously
12df0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
12e00 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69  HUNKALLOC 12 whi
12e10 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64  ch is now unused
12e20 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51  . */ .#define SQ
12e30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
12e40 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20  ASIDE    13  /* 
12e50 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
12e60 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
12e70 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34  _PCACHE       14
12e80 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
12e90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
12ea0 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20  FIG_GETPCACHE   
12eb0 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f   15  /* no-op */
12ec0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12ed0 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20  CONFIG_LOG      
12ee0 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63      16  /* xFunc
12ef0 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
12f00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
12f10 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37  _URI          17
12f20 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
12f30 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12f40 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31  G_PCACHE2      1
12f50 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  8  /* sqlite3_pc
12f60 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a  ache_methods2* *
12f70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
12f80 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
12f90 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69  E2   19  /* sqli
12fa0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
12fb0 64 73 32 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  ds2* */../*.** C
12fc0 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
12fd0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e  e Connection Con
12fe0 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
12ff0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
13000 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
13010 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
13020 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
13030 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
13040 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
13050 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
13060 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
13070 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
13080 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
13090 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
130a0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
130b0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
130c0 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
130d0 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
130e0 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
130f0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
13100 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
13110 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
13120 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
13130 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
13140 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62  from [sqlite3_db
13150 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
13160 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
13170 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
13180 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
13190 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
131a0 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
131b0 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
131c0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
131d0 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
131e0 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
131f0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13200 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
13210 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
13220 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
13230 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
13240 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
13250 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
13260 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  hree additional 
13270 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
13280 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a  etermine the .**
13290 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f   [lookaside memo
132a0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f  ry allocator] co
132b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
132c0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
132d0 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54  nnection]..** ^T
132e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
132f0 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72  t (the third par
13300 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
13310 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
13320 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
13330 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66  to a memory buff
13340 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f  er to use for lo
13350 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a  okaside memory..
13360 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
13370 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65  gument after the
13380 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
13390 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a  _LOOKASIDE verb.
133a0 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69  ** may be NULL i
133b0 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c  n which case SQL
133c0 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74  ite will allocat
133d0 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69  e the.** lookasi
133e0 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66  de buffer itself
133f0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
13400 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20  malloc()]. ^The 
13410 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
13420 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
13430 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
13440 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e   buffer slot.  ^
13450 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
13460 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nt is the number
13470 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54   of.** slots.  T
13480 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  he size of the b
13490 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72  uffer in the fir
134a0 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
134b0 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e   be greater than
134c0 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  .** or equal to 
134d0 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74  the product of t
134e0 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
134f0 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20  ird arguments.  
13500 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75  The buffer.** mu
13510 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
13520 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64   an 8-byte bound
13530 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65  ary.  ^If the se
13540 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
13550 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  .** SQLITE_DBCON
13560 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73  FIG_LOOKASIDE is
13570 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20   not a multiple 
13580 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65  of 8, it is inte
13590 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65  rnally.** rounde
135a0 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65  d down to the ne
135b0 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69  xt smaller multi
135c0 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65  ple of 8.  ^(The
135d0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
135e0 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  y.** configurati
135f0 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73  on for a databas
13600 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e  e connection can
13610 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64   only be changed
13620 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f   when that.** co
13630 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  nnection is not 
13640 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20  currently using 
13650 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
13660 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f  , or in other wo
13670 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  rds.** when the 
13680 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20  "current value" 
13690 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
136a0 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75  sqlite3_db_statu
136b0 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e  s](D,[SQLITE_CON
136c0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e  FIG_LOOKASIDE],.
136d0 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20  ..) is zero..** 
136e0 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
136f0 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
13700 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69  ide memory confi
13710 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f  guration when lo
13720 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72  okaside.** memor
13730 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76  y is in use leav
13740 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  es the configura
13750 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61  tion unchanged a
13760 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b  nd returns .** [
13770 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c  SQLITE_BUSY].)^<
13780 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
13790 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
137a0 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a  NABLE_FKEY</dt>.
137b0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
137c0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
137d0 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
137e0 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e  e the enforcemen
137f0 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  t of.** [foreign
13800 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73   key constraints
13810 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64  ].  There should
13820 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
13830 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
13840 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
13850 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
13860 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
13870 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72  disable FK enfor
13880 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74  cement,.** posit
13890 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b  ive to enable FK
138a0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20   enforcement or 
138b0 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
138c0 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
138d0 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20  .** unchanged.  
138e0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
138f0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
13900 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
13910 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
13920 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
13930 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
13940 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  her FK enforceme
13950 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a  nt is off or on.
13960 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
13970 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
13980 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
13990 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
139a0 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
139b0 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66   case the FK enf
139c0 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67  orcement setting
139d0 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
139e0 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
139f0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
13a00 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
13a10 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  IGGER</dt>.** <d
13a20 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
13a30 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
13a40 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52  e or disable [CR
13a50 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
13a60 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65  riggers]..** The
13a70 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
13a80 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
13a90 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
13aa0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
13ab0 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
13ac0 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
13ad0 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f   triggers,.** po
13ae0 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
13af0 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67   triggers or neg
13b00 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
13b10 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61  he setting uncha
13b20 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
13b30 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
13b40 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
13b50 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
13b60 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
13b70 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
13b80 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69  cate whether tri
13b90 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c  ggers are disabl
13ba0 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a  ed or enabled.**
13bb0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
13bc0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
13bd0 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
13be0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
13bf0 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
13c00 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ase the trigger 
13c10 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
13c20 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
13c30 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
13c40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13c50 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
13c60 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20  SIDE       1001 
13c70 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e   /* void* int in
13c80 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
13c90 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
13ca0 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30  BLE_FKEY     100
13cb0 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  2  /* int int* *
13cc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13cd0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
13ce0 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20  _TRIGGER  1003  
13cf0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a  /* int int* */..
13d00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13d10 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
13d20 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
13d30 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e  lt Codes.**.** ^
13d40 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
13d50 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
13d60 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
13d70 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
13d80 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
13d90 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
13da0 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
13db0 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
13dc0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
13dd0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
13de0 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
13df0 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
13e00 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
13e10 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
13e20 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
13e30 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
13e40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13e50 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
13e60 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  wid.**.** ^Each 
13e70 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69  entry in an SQLi
13e80 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75  te table has a u
13e90 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
13ea0 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
13eb0 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
13ec0 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
13ed0 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
13ee0 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
13ef0 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
13f00 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
13f10 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
13f20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
13f30 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
13f40 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
13f50 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
13f60 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
13f70 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
13f80 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
13f90 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
13fa0 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
13fb0 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
13fc0 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
13fd0 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
13fe0 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  id..**.** ^This 
13ff0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
14000 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
14010 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
14020 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
14030 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64  SERT] into the d
14040 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65  atabase from the
14050 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
14060 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ction].** in the
14070 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
14080 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 74 65 20    ^As of SQLite 
14090 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 74  version 3.7.7, t
140a0 68 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  his routines.** 
140b0 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 73 74  records the last
140c0 20 69 6e 73 65 72 74 20 72 6f 77 69 64 20 6f 66   insert rowid of
140d0 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 79 20 74   both ordinary t
140e0 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 72 74 75  ables and [virtu
140f0 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e  al tables]..** ^
14100 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
14110 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61   [INSERT]s.** ha
14120 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
14130 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73   on that databas
14140 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65  e connection, ze
14150 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
14160 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49  **.** ^(If an [I
14170 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
14180 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f  thin a trigger o
14190 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74  r within a [virt
141a0 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65  ual table].** me
141b0 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20  thod, then this 
141c0 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74  routine will ret
141d0 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  urn the [rowid] 
141e0 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a  of the inserted.
141f0 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61  ** row as long a
14200 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  s the trigger or
14210 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
14220 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67  ethod is running
14230 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68  ..** But once th
14240 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
14250 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
14260 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75  d ends, the valu
14270 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62  e returned .** b
14280 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  y this routine r
14290 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69  everts to what i
142a0 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65  t was before the
142b0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
142c0 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74  ual.** table met
142d0 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a  hod began.)^.**.
142e0 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
142f0 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
14300 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
14310 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
14320 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
14330 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
14340 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
14350 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
14360 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
14370 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
14380 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
14390 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
143a0 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
143b0 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
143c0 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
143d0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
143e0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
143f0 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
14400 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
14410 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
14420 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
14430 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
14440 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
14450 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
14460 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
14470 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
14480 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
14490 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
144a0 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
144b0 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
144c0 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
144d0 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
144e0 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
144f0 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
14500 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
14510 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
14520 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
14530 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
14540 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
14550 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
14560 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
14570 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
14580 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
14590 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
145a0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
145b0 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
145c0 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
145d0 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
145e0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
145f0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
14600 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
14610 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
14620 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
14630 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
14640 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
14650 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
14660 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
14670 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
14680 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
14690 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
146a0 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
146b0 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
146c0 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
146d0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
146e0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
146f0 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
14700 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
14710 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
14720 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
14730 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
14740 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
14750 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  wid]..*/.sqlite3
14760 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
14770 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
14780 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
14790 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
147a0 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
147b0 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
147c0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
147d0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
147e0 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61  number of databa
147f0 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72  se rows that wer
14800 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20  e changed.** or 
14810 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
14820 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
14830 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
14840 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
14850 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  .** on the [data
14860 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
14870 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
14880 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
14890 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61  r..** ^(Only cha
148a0 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69  nges that are di
148b0 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64  rectly specified
148c0 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d   by the [INSERT]
148d0 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f  , [UPDATE],.** o
148e0 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
148f0 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64  ment are counted
14900 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61  .  Auxiliary cha
14910 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a  nges caused by.*
14920 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66  * triggers or [f
14930 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
14940 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ns] are not coun
14950 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a  ted.)^ Use the.*
14960 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  * [sqlite3_total
14970 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
14980 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65  tion to find the
14990 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
149a0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c   changes.** incl
149b0 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61  uding changes ca
149c0 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73  used by triggers
149d0 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79   and foreign key
149e0 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   actions..**.** 
149f0 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
14a00 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75  ew that are simu
14a10 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53  lated by an [INS
14a20 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d  TEAD OF trigger]
14a30 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  .** are not coun
14a40 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20  ted.  Only real 
14a50 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72  table changes ar
14a60 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  e counted..**.**
14a70 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65   ^(A "row change
14a80 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f  " is a change to
14a90 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66   a single row of
14aa0 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a   a single table.
14ab0 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20  ** caused by an 
14ac0 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20  INSERT, DELETE, 
14ad0 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d  or UPDATE statem
14ae0 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a  ent.  Rows that.
14af0 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61  ** are changed a
14b00 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f  s side effects o
14b10 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  f [REPLACE] cons
14b20 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
14b30 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20  n,.** rollback, 
14b40 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
14b50 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20  , [DROP TABLE], 
14b60 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a  or by any other.
14b70 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f  ** mechanisms do
14b80 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69   not count as di
14b90 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
14ba0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69  .)^.**.** A "tri
14bb0 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73  gger context" is
14bc0 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63   a scope of exec
14bd0 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e  ution that begin
14be0 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69  s and.** ends wi
14bf0 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66  th the script of
14c00 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47   a [CREATE TRIGG
14c10 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a  ER | trigger]. .
14c20 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74  ** Most SQL stat
14c30 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76  ements are.** ev
14c40 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20  aluated outside 
14c50 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20  of any trigger. 
14c60 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f   This is the "to
14c70 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67  p level".** trig
14c80 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66  ger context.  If
14c90 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73   a trigger fires
14ca0 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
14cb0 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72  vel, a.** new tr
14cc0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73  igger context is
14cd0 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65   entered for the
14ce0 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61   duration of tha
14cf0 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72  t one.** trigger
14d00 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63  .  Subtriggers c
14d10 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74  reate subcontext
14d20 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61  s for their dura
14d30 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  tion..**.** ^Cal
14d40 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ling [sqlite3_ex
14d50 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
14d60 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
14d70 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ively does.** no
14d80 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74  t create a new t
14d90 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
14da0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
14db0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
14dc0 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63   number of direc
14dd0 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e  t row changes in
14de0 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63   the.** most rec
14df0 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
14e00 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74  TE, or DELETE st
14e10 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
14e20 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67  he same.** trigg
14e30 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
14e40 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61  * ^Thus, when ca
14e50 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f  lled from the to
14e60 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75  p level, this fu
14e70 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
14e80 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
14e90 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
14ea0 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
14eb0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
14ec0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73  LETE.** that als
14ed0 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68  o occurred at th
14ee0 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28  e top level.  ^(
14ef0 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  Within the body 
14f00 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a  of a trigger,.**
14f10 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
14f20 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65  nges() interface
14f30 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74   can be called t
14f40 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
14f50 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20  r of.** changes 
14f60 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
14f70 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
14f80 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
14f90 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
14fa0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
14fb0 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d   body of the sam
14fc0 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f  e trigger..** Ho
14fd0 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65  wever, the numbe
14fe0 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  r returned does 
14ff0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
15000 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ges.** caused by
15010 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e   subtriggers sin
15020 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68  ce those have th
15030 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e  eir own context.
15040 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
15050 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
15060 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
15070 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
15080 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
15090 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
150a0 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
150b0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
150c0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
150d0 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
150e0 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
150f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15100 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
15110 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
15120 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
15130 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
15140 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
15150 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
15160 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
15170 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
15180 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
15190 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
151a0 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
151b0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
151c0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
151d0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
151e0 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61  umber of row cha
151f0 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
15200 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44  INSERT],.** [UPD
15210 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
15220 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63   statements sinc
15230 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
15240 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20  connection] was 
15250 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65  opened..** ^(The
15260 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20   count returned 
15270 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
15280 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75  _changes() inclu
15290 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a  des all changes.
152a0 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45  ** from all [CRE
152b0 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
152c0 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20  igger] contexts 
152d0 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65  and changes made
152e0 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   by.** [foreign 
152f0 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f  key actions]. Ho
15300 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
15310 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
15320 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
15330 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  d to implement [
15340 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
15350 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
15360 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
15370 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44  rocessing, or [D
15380 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65  ROP TABLE] proce
15390 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63  ssing.  The.** c
153a0 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
153b0 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69  clude rows of vi
153c0 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e  ews that fire an
153d0 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
153e0 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68  gger],.** though
153f0 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20   if the INSTEAD 
15400 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73  OF trigger makes
15410 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20   changes of its 
15420 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67  own, those chang
15430 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74  es .** are count
15440 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71  ed.)^.** ^The sq
15450 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
15460 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ges() function c
15470 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65  ounts the change
15480 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20  s as soon as.** 
15490 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
154a0 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73  at makes them is
154b0 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e   completed (when
154c0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
154d0 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73  andle.** is pass
154e0 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ed to [sqlite3_r
154f0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
15500 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29  te3_finalize()])
15510 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
15520 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
15530 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
15540 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
15550 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
15560 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
15570 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
15580 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
15590 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
155a0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
155b0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
155c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
155d0 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
155e0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
155f0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
15600 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
15610 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
15620 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
15630 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
15640 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
15650 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
15660 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
15670 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
15680 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
15690 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20  ing Query.**.** 
156a0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63  ^This function c
156b0 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e  auses any pendin
156c0 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  g database opera
156d0 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e  tion to abort an
156e0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69  d.** return at i
156f0 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f  ts earliest oppo
15700 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f  rtunity. This ro
15710 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c  utine is typical
15720 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20  ly.** called in 
15730 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73  response to a us
15740 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61  er action such a
15750 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63  s pressing "Canc
15760 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43  el".** or Ctrl-C
15770 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20   where the user 
15780 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65  wants a long que
15790 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  ry operation to 
157a0 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74  halt.** immediat
157b0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  ely..**.** ^It i
157c0 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  s safe to call t
157d0 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d  his routine from
157e0 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72   a thread differ
157f0 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20  ent from the.** 
15800 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63  thread that is c
15810 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
15820 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70   the database op
15830 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74  eration.  But it
15840 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20  .** is not safe 
15850 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
15860 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74  tine with a [dat
15870 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15880 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f  ] that.** is clo
15890 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f  sed or might clo
158a0 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  se before sqlite
158b0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
158c0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  turns..**.** ^If
158d0 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
158e0 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
158f0 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
15900 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
15910 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
15920 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
15930 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
15940 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
15950 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
15960 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
15970 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
15980 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
15990 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ^An SQL operatio
159a0 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72  n that is interr
159b0 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72  upted will retur
159c0 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  n [SQLITE_INTERR
159d0 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  UPT]..** ^If the
159e0 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c   interrupted SQL
159f0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
15a00 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
15a10 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
15a20 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20  at is inside an 
15a30 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
15a40 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
15a50 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
15a60 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c  n.** will be rol
15a70 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
15a80 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ically..**.** ^T
15a90 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
15aa0 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20  rupt(D) call is 
15ab0 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20  in effect until 
15ac0 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75  all currently ru
15ad0 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
15ae0 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61  tements on [data
15af0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
15b00 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41   D complete.  ^A
15b10 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65  ny new SQL state
15b20 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
15b30 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
15b40 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
15b50 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64  rrupt() call and
15b60 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20   before the .** 
15b70 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
15b80 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  ts reaches zero 
15b90 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  are interrupted 
15ba0 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62  as if they had b
15bb0 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70  een.** running p
15bc0 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69  rior to the sqli
15bd0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
15be0 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20  call.  ^New SQL 
15bf0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
15c00 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
15c10 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67  fter the running
15c20 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74   statement count
15c30 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
15c40 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65  e.** not effecte
15c50 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
15c60 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a  _interrupt()..**
15c70 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69   ^A call to sqli
15c80 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
15c90 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65   that occurs whe
15ca0 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72  n there are no r
15cb0 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
15cc0 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f  atements is a no
15cd0 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65  -op and has no e
15ce0 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61  ffect on SQL sta
15cf0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
15d00 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
15d10 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
15d20 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72  terrupt() call r
15d30 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
15d40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
15d50 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
15d60 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
15d70 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69  nterrupt()].** i
15d80 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62  s running then b
15d90 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c  ad things will l
15da0 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f  ikely happen..*/
15db0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
15dc0 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
15dd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
15de0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
15df0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
15e00 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a  t Is Complete.**
15e10 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
15e20 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75  es are useful du
15e30 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e  ring command-lin
15e40 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72  e input to deter
15e50 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63  mine if the.** c
15e60 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
15e70 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66   text seems to f
15e80 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53  orm a complete S
15e90 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a  QL statement or.
15ea0 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
15eb0 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
15ec0 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
15ed0 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a  the text into.**
15ee0 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
15ef0 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ing.  ^These rou
15f00 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69  tines return 1 i
15f10 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
15f20 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
15f30 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
15f40 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  QL statement.  ^
15f50 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
15f60 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
15f70 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
15f80 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
15f90 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
15fa0 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66   not a prefix of
15fb0 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65   a.** well-forme
15fc0 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  d CREATE TRIGGER
15fd0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65   statement.  ^Se
15fe0 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
15ff0 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
16000 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
16010 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
16020 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
16030 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
16040 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
16050 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
16060 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
16070 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
16080 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
16090 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
160a0 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
160b0 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
160c0 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61  ator.  ^Whitespa
160d0 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e  ce.** and commen
160e0 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74  ts that follow t
160f0 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c  he final semicol
16100 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a  on are ignored..
16110 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
16120 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
16130 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
16140 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
16150 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ^If a.** memory 
16160 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
16170 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f  , then SQLITE_NO
16180 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  MEM is returned.
16190 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
161a0 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
161b0 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
161c0 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
161d0 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
161e0 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
161f0 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
16200 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61  * ^(If SQLite ha
16210 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69  s not been initi
16220 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71  alized using [sq
16230 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
16240 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f  ()] prior .** to
16250 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65   invoking sqlite
16260 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74  3_complete16() t
16270 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  hen sqlite3_init
16280 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
16290 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ked.** automatic
162a0 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
162b0 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49  complete16().  I
162c0 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a  f that initializ
162d0 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20  ation fails,.** 
162e0 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
162f0 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
16300 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
16310 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f  will be non-zero
16320 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
16330 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
16340 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69   the input SQL i
16350 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a  s complete.)^.**
16360 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
16370 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
16380 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
16390 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
163a0 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
163b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
163c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
163d0 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
163e0 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
163f0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
16400 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
16410 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
16420 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
16430 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
16440 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
16450 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
16460 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
16470 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
16480 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
16490 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
164a0 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
164b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
164c0 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
164d0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68  back function th
164e0 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
164f0 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  ked whenever.** 
16500 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
16510 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74  de to open a dat
16520 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74  abase table that
16530 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
16540 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
16550 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20  s locked..**.** 
16560 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
16570 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
16580 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
16590 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
165a0 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69  RR_BLOCKED].** i
165b0 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
165c0 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
165d0 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
165e0 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79  k.  ^If the busy
165f0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
16600 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
16610 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68  he callback migh
16620 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
16630 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
16640 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
16650 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
16660 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
16670 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
16680 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
16690 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
166a0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
166b0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
166c0 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65  dler().  ^The se
166d0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
166e0 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
166f0 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
16700 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
16710 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
16720 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
16730 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66  * been invoked f
16740 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20  or this locking 
16750 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
16760 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
16770 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
16780 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
16790 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
167a0 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
167b0 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
167c0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
167d0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
167e0 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e  OCKED] is return
167f0 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  ed..** ^If the c
16800 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
16810 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
16820 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
16830 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  * is made to ope
16840 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
16850 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74  or reading and t
16860 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
16870 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
16880 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
16890 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
168a0 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
168b0 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
168c0 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
168d0 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
168e0 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64  on. ^If SQLite d
168f0 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
16900 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
16910 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  .** handler coul
16920 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65  d result in a de
16930 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
16940 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
16950 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
16960 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ].** or [SQLITE_
16970 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
16980 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
16990 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ng the busy hand
169a0 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ler..** Consider
169b0 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
169c0 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
169d0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
169e0 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
169f0 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
16a00 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
16a10 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
16a20 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
16a30 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
16a40 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
16a50 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
16a60 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
16a70 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
16a80 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
16a90 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
16aa0 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
16ab0 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
16ac0 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
16ad0 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
16ae0 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
16af0 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
16b00 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
16b10 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
16b20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
16b30 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
16b40 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
16b50 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
16b60 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
16b70 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
16b80 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
16b90 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
16ba0 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
16bb0 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
16bc0 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
16bd0 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
16be0 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
16bf0 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
16c00 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
16c10 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
16c20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
16c30 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
16c40 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
16c50 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55   ^The [SQLITE_BU
16c60 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e  SY] error is con
16c70 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54  verted to [SQLIT
16c80 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
16c90 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
16ca0 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65  is in the middle
16cb0 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e   of a large tran
16cc0 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c  saction where al
16cd0 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73  l the.** changes
16ce0 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e   will not fit in
16cf0 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  to the in-memory
16d00 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20   cache.  SQLite 
16d10 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20  will.** already 
16d20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20  hold a RESERVED 
16d30 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61  lock on the data
16d40 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69  base file, but i
16d50 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72  t needs.** to pr
16d60 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20  omote this lock 
16d70 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20  to EXCLUSIVE so 
16d80 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c  that it can spil
16d90 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73  l cache.** pages
16da0 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
16db0 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20  se file without 
16dc0 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65  harm to concurre
16dd0 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20  nt.** readers.  
16de0 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65  ^If it is unable
16df0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20   to promote the 
16e00 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69  lock, then the i
16e10 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68  n-memory.** cach
16e20 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69  e will be left i
16e30 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e  n an inconsisten
16e40 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74  t state and so t
16e50 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65  he error.** code
16e60 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f   is promoted fro
16e70 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79  m the relatively
16e80 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f   benign [SQLITE_
16e90 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20  BUSY] to.** the 
16ea0 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c  more severe [SQL
16eb0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
16ec0 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72  D].  ^This error
16ed0 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a   code promotion.
16ee0 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74  ** forces an aut
16ef0 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20  omatic rollback 
16f00 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20  of the changes. 
16f10 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68   See the.** <a h
16f20 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69  ref="/cvstrac/wi
16f30 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46  ki?p=CorruptionF
16f40 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
16f50 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f  r">.** Corruptio
16f60 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
16f70 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67  ror</a> wiki pag
16f80 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69  e for a discussi
16f90 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69  on of why.** thi
16fa0 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a  s is important..
16fb0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
16fc0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
16fd0 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
16fe0 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
16ff0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
17000 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
17010 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
17020 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
17030 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
17040 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20  set handler.)^  
17050 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69  ^Note that calli
17060 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
17070 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77  _timeout()].** w
17080 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20  ill also set or 
17090 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68  clear the busy h
170a0 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  andler..**.** Th
170b0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
170c0 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20  should not take 
170d0 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63  any actions whic
170e0 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20  h modify the.** 
170f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17100 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
17110 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
17120 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  r.  Any such act
17130 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
17140 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
17150 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
17160 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
17170 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
17180 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17190 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
171a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
171b0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
171c0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
171d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
171e0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
171f0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
17200 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
17210 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
17220 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
17230 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
17240 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
17250 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
17260 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
17270 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
17280 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
17290 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
172a0 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
172b0 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
172c0 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
172d0 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
172e0 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
172f0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
17300 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
17310 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
17320 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
17330 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
17340 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
17350 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
17360 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
17370 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
17380 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
17390 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
173a0 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
173b0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
173c0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
173d0 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
173e0 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
173f0 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
17400 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
17410 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
17420 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
17430 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
17440 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
17450 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
17460 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
17470 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17480 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76  ion] any any giv
17490 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
174a0 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
174b0 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
174c0 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
174d0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
174e0 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
174f0 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
17500 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
17510 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
17520 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a  s cleared.)^.*/.
17530 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
17540 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
17550 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
17560 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
17570 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
17580 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
17590 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eries.**.** This
175a0 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74   is a legacy int
175b0 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70  erface that is p
175c0 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63  reserved for bac
175d0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
175e0 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20  lity..** Use of 
175f0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
17600 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65  s not recommende
17610 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  d..**.** Definit
17620 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
17630 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
17640 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
17650 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
17660 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
17670 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
17680 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
17690 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
176a0 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
176b0 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
176c0 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
176d0 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
176e0 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
176f0 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
17700 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
17710 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
17720 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
17730 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
17740 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
17750 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
17760 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
17770 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
17780 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
17790 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
177a0 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
177b0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
177c0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
177d0 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
177e0 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
177f0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
17800 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
17810 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
17820 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
17830 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
17840 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
17850 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
17860 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
17870 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
17880 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
17890 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
178a0 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
178b0 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
178c0 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
178d0 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
178e0 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
178f0 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
17900 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
17910 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
17920 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
17930 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
17940 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
17950 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
17960 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
17970 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
17980 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
17990 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
179a0 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
179b0 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
179c0 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
179d0 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
179e0 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
179f0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
17a00 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
17a10 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
17a20 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
17a30 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
17a40 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61  )]..**.** ^(As a
17a50 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
17a60 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
17a70 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
17a80 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
17a90 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
17aa0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
17ab0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
17ac0 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
17ad0 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
17ae0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
17af0 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
17b00 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
17b10 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
17b20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
17b30 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
17b40 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
17b50 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
17b60 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
17b70 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
17b80 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
17b90 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
17ba0 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
17bb0 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
17bc0 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
17bd0 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
17be0 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
17bf0 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
17c00 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
17c10 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
17c20 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
17c30 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
17c40 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
17c50 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
17c60 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
17c70 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
17c80 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
17c90 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
17ca0 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
17cb0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
17cc0 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
17cd0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
17ce0 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
17cf0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
17d00 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
17d10 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
17d20 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
17d30 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
17d40 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
17d50 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
17d60 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
17d70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
17d80 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
17d90 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
17da0 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
17db0 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
17dc0 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
17dd0 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
17de0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
17df0 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
17e00 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  s 2nd parameter 
17e10 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65  and returns a re
17e20 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
17e30 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
17e40 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
17e50 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
17e60 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  fter the applica
17e70 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
17e80 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c  d with the resul
17e90 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67  t from sqlite3_g
17ea0 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69  et_table(),.** i
17eb0 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20  t must pass the 
17ec0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69  result table poi
17ed0 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
17ee0 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
17ef0 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
17f00 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
17f10 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
17f20 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
17f30 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
17f40 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
17f50 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
17f60 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
17f70 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
17f80 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
17f90 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
17fa0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
17fb0 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
17fc0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
17fd0 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
17fe0 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
17ff0 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
18000 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
18010 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
18020 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
18030 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
18040 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
18050 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
18060 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
18070 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
18080 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
18090 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
180a0 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
180b0 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
180c0 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
180d0 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
180e0 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
180f0 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
18100 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
18110 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
18120 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
18130 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
18140 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
18150 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
18160 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
18170 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
18180 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
18190 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
181a0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
181b0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
181c0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69  _errmsg()]..*/.i
181d0 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
181e0 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
181f0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
18200 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
18210 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
18220 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
18230 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
18240 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
18250 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
18260 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
18270 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
18280 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
18290 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
182a0 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
182b0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
182c0 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
182d0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
182e0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
182f0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
18300 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
18310 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
18320 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
18330 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69   */.);.void sqli
18340 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
18350 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
18360 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18370 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
18380 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
18390 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
183a0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
183b0 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  k-alikes of the 
183c0 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
183d0 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
183e0 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
183f0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
18400 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
18410 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
18420 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
18430 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
18440 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
18450 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
18460 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
18470 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
18480 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
18490 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
184a0 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
184b0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
184c0 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
184d0 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
184e0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
184f0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
18500 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
18510 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
18520 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
18530 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
18540 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
18550 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
18560 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
18570 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
18580 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
18590 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
185a0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
185b0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
185c0 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
185d0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
185e0 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
185f0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
18600 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
18610 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
18620 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
18630 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
18640 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
18650 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
18660 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
18670 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
18680 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
18690 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
186a0 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
186b0 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
186c0 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
186d0 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
186e0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
186f0 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
18700 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
18710 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
18720 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
18730 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
18740 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
18750 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
18760 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
18770 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
18780 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
18790 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
187a0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
187b0 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
187c0 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
187d0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
187e0 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
187f0 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
18800 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
18810 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
18820 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
18830 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
18840 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
18850 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
18860 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
18870 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
18880 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
18890 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
188a0 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
188b0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
188c0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
188d0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
188e0 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
188f0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
18900 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
18910 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
18920 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
18930 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
18940 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
18950 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
18960 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
18970 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
18980 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
18990 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
189a0 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
189b0 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
189c0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
189d0 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
189e0 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
189f0 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
18a00 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
18a10 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
18a20 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
18a30 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
18a40 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
18a50 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
18a60 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
18a70 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
18a80 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
18a90 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
18aa0 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
18ab0 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
18ac0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
18ad0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
18ae0 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
18af0 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
18b00 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
18b10 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
18b20 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
18b30 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
18b40 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
18b50 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
18b60 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
18b70 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
18b80 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
18b90 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
18ba0 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
18bb0 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
18bc0 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
18bd0 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
18be0 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
18bf0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
18c00 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
18c10 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
18c20 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
18c30 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
18c40 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
18c50 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
18c60 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
18c70 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
18c80 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
18c90 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
18ca0 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
18cb0 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
18cc0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
18cd0 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
18ce0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
18cf0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
18d00 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
18d10 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
18d20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
18d30 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
18d40 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
18d50 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
18d60 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
18d70 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
18d80 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
18d90 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
18da0 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
18db0 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
18dc0 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
18dd0 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
18de0 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
18df0 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
18e00 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
18e10 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
18e20 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
18e30 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
18e40 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
18e50 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
18e60 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
18e70 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
18e80 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
18e90 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
18ea0 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
18eb0 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
18ec0 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
18ed0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
18ee0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
18ef0 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
18f00 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
18f10 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
18f20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
18f30 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
18f40 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
18f50 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
18f60 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
18f70 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
18f80 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
18f90 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
18fa0 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
18fb0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
18fc0 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
18fd0 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
18fe0 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
18ff0 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
19000 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
19010 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
19020 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
19030 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
19040 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
19050 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
19060 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
19070 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
19080 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
19090 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
190a0 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
190b0 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
190c0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
190d0 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
190e0 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
190f0 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
19100 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
19110 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
19120 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
19130 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
19140 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
19150 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
19160 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
19170 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
19180 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
19190 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
191a0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
191b0 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
191c0 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
191d0 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
191e0 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
191f0 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
19200 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
19210 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
19220 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
19230 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
19240 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
19250 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
19260 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
19270 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
19280 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
19290 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
192a0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
192b0 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
192c0 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
192d0 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
192e0 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20  ring.)^.*/.char 
192f0 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
19300 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
19310 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
19320 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
19330 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
19340 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
19350 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
19360 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
19370 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
19380 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
19390 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
193a0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
193b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
193c0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
193d0 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
193e0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
193f0 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
19400 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
19410 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
19420 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
19430 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
19440 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
19450 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
19460 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
19470 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
19480 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
19490 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
194a0 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
194b0 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
194c0 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
194d0 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
194e0 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
194f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
19500 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
19510 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
19520 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
19530 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
19540 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
19550 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
19560 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
19570 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
19580 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
19590 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
195a0 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
195b0 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
195c0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
195d0 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
195e0 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
195f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
19600 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
19610 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
19620 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
19630 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
19640 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ter..**.** ^Call
19650 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
19660 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
19670 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
19680 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
19690 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
196a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
196b0 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
196c0 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
196d0 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
196e0 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  used.  ^The sqli
196f0 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
19700 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
19710 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
19720 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
19730 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
19740 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
19750 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
19760 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
19770 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
19780 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
19790 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
197a0 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
197b0 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
197c0 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
197d0 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
197e0 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
197f0 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
19800 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
19810 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
19820 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
19830 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
19840 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
19850 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
19860 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
19870 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
19880 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
19890 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
198a0 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
198b0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
198c0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
198d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
198e0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
198f0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74  e3_realloc() int
19900 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
19910 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70  to resize a.** p
19920 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rior memory allo
19930 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20  cation to be at 
19940 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77  least N bytes, w
19950 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
19960 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
19970 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  r.  The memory a
19980 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
19990 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66  resized is the f
199a0 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
199b0 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69  r.)^ ^ If the fi
199c0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
199d0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
199e0 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  ().** is a NULL 
199f0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
19a00 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
19a10 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
19a20 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
19a30 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69  loc(N) where N i
19a40 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
19a50 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
19a60 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
19a70 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70  ^If the second p
19a80 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
19a90 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73  te3_realloc() is
19aa0 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
19ab0 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
19ac0 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
19ad0 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
19ae0 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
19af0 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50  _free(P) where P
19b00 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
19b10 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
19b20 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
19b30 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   ^sqlite3_reallo
19b40 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  c() returns a po
19b50 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
19b60 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
19b70 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
19b80 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
19b90 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e  ULL if sufficien
19ba0 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76  t memory is unav
19bb0 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  ailable..** ^If 
19bc0 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
19bd0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
19be0 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
19bf0 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
19c00 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
19c10 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
19c20 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
19c30 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
19c40 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
19c50 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61  ite3_realloc() a
19c60 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
19c70 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
19c80 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
19c90 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
19ca0 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ns NULL, then th
19cb0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
19cc0 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65  on.** is not fre
19cd0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ed..**.** ^The m
19ce0 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
19cf0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
19d00 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
19d10 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
19d20 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
19d30 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
19d40 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72  yte boundary, or
19d50 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20   to a.** 4 byte 
19d60 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20  boundary if the 
19d70 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41  [SQLITE_4_BYTE_A
19d80 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63  LIGNED_MALLOC] c
19d90 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
19da0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
19db0 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
19dc0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
19dd0 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
19de0 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
19df0 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
19e00 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
19e10 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
19e20 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
19e30 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
19e40 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
19e50 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
19e60 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
19e70 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
19e80 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
19e90 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
19ea0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
19eb0 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
19ec0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64  ..**.** The Wind
19ed0 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
19ee0 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   layer calls.** 
19ef0 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
19f00 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
19f10 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
19f20 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
19f30 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
19f40 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
19f50 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
19f60 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
19f70 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
19f80 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
19f90 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
19fa0 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
19fb0 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
19fc0 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72  cation errors ar
19fd0 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
19fe0 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f  ** they are repo
19ff0 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
1a000 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
1a010 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
1a020 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
1a030 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
1a040 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
1a050 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
1a060 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1a070 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1a080 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
1a090 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
1a0a0 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
1a0b0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
1a0c0 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
1a0d0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1a0e0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
1a0f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1a100 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
1a110 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
1a120 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
1a130 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
1a140 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
1a150 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
1a160 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
1a170 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
1a180 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
1a190 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1a1a0 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
1a1b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
1a1c0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
1a1d0 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
1a1e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
1a1f0 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
1a200 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
1a210 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ee(void*);../*.*
1a220 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1a230 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
1a240 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51  tistics.**.** SQ
1a250 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
1a260 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
1a270 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
1a280 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
1a290 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
1a2a0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
1a2b0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
1a2c0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1a2d0 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
1a2e0 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
1a2f0 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
1a300 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
1a310 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  bsystem..**.** ^
1a320 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
1a330 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
1a340 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
1a350 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
1a360 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  ** of memory cur
1a370 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
1a380 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
1a390 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20   not freed)..** 
1a3a0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1a3b0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1a3c0 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
1a3d0 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
1a3e0 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
1a3f0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1a400 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68  ] since the high
1a410 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77  -water mark.** w
1a420 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20  as last reset.  
1a430 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
1a440 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1a450 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1a460 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1a470 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1a480 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
1a490 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65  overhead.** adde
1a4a0 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
1a4b0 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
1a4c0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
1a4d0 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20  lloc()],.** but 
1a4e0 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
1a4f0 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
1a500 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
1a510 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69  library.** routi
1a520 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
1a530 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
1a540 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  call..**.** ^The
1a550 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
1a560 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
1a570 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
1a580 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c  value of.** [sql
1a590 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1a5a0 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ()] if and only 
1a5b0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1a5c0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
1a5d0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1a5e0 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54  ()] is true.  ^T
1a5f0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1a600 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
1a610 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1a620 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
1a630 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1a640 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
1a650 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  et..*/.sqlite3_i
1a660 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1a670 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
1a680 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
1a690 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1a6a0 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
1a6b0 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
1a6c0 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
1a6d0 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
1a6e0 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c  erator.**.** SQL
1a6f0 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68  ite contains a h
1a700 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
1a710 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72  do-random number
1a720 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47   generator (PRNG
1a730 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c  ) used to.** sel
1a740 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49  ect random [ROWI
1a750 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e  D | ROWIDs] when
1a760 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72   inserting new r
1a770 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61  ecords into a ta
1a780 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65  ble that.** alre
1a790 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72  ady uses the lar
1a7a0 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52  gest possible [R
1a7b0 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47  OWID].  The PRNG
1a7c0 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f   is also used fo
1a7d0 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69  r.** the build-i
1a7e0 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72  n random() and r
1a7f0 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20  andomblob() SQL 
1a800 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73  functions.  This
1a810 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
1a820 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  s.** application
1a830 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
1a840 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74  same PRNG for ot
1a850 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  her purposes..**
1a860 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74  .** ^A call to t
1a870 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
1a880 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
1a890 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
1a8a0 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ffer P..**.** ^T
1a8b0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
1a8c0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e  is routine is in
1a8d0 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e  voked (either in
1a8e0 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a  ternally or by.*
1a8f0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
1a900 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73  n) the PRNG is s
1a910 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
1a920 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a  omness obtained.
1a930 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ** from the xRan
1a940 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
1a950 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
1a960 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1a970 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73  ct..** ^On all s
1a980 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
1a990 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64  tions, the pseud
1a9a0 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
1a9b0 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
1a9c0 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
1a9d0 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
1a9e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
1a9f0 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
1aa00 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64   method..*/.void
1aa10 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
1aa20 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
1aa30 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
1aa40 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
1aa50 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
1aa60 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
1aa70 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
1aa80 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
1aa90 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1aaa0 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
1aab0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1aac0 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
1aad0 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
1aae0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
1aaf0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1ab00 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1ab10 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
1ab20 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
1ab30 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
1ab40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1ab50 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1ab60 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
1ab70 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
1ab80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1ab90 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1aba0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1abb0 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
1abc0 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
1abd0 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
1abe0 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
1abf0 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
1ac00 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
1ac10 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
1ac20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1ac30 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1ac40 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
1ac50 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
1ac60 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
1ac70 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1ac80 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
1ac90 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1aca0 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
1acb0 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
1acc0 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
1acd0 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
1ace0 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
1acf0 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
1ad00 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
1ad10 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
1ad20 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
1ad30 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
1ad40 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
1ad50 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
1ad60 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
1ad70 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
1ad80 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1ad90 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1ada0 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
1adb0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
1adc0 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
1add0 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
1ade0 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
1adf0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
1ae00 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
1ae10 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
1ae20 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
1ae30 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
1ae40 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
1ae50 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
1ae60 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
1ae70 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1ae80 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
1ae90 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
1aea0 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
1aeb0 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
1aec0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1aed0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
1aee0 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
1aef0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1af00 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
1af10 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
1af20 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
1af30 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
1af40 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
1af50 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
1af60 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
1af70 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
1af80 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
1af90 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1afa0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1afb0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
1afc0 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
1afd0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
1afe0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1aff0 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
1b000 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
1b010 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
1b020 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1b030 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
1b040 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
1b050 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
1b060 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
1b070 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
1b080 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
1b090 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
1b0a0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
1b0b0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1b0c0 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
1b0d0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
1b0e0 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
1b0f0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
1b100 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
1b110 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1b120 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ized..**.** ^If 
1b130 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
1b140 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
1b150 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
1b160 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1b170 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1b180 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
1b190 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
1b1a0 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
1b1b0 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
1b1c0 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
1b1d0 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
1b1e0 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
1b1f0 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
1b200 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
1b210 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
1b220 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
1b230 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
1b240 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
1b250 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
1b260 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
1b270 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
1b280 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
1b290 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
1b2a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
1b2b0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1b2c0 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
1b2d0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1b2e0 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
1b2f0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1b300 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
1b310 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
1b320 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
1b330 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
1b340 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
1b350 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
1b360 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
1b370 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
1b380 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
1b390 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
1b3a0 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
1b3b0 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
1b3c0 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
1b3d0 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
1b3e0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1b3f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1b400 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
1b410 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
1b420 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
1b430 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
1b440 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
1b450 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
1b460 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
1b470 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
1b480 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
1b490 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
1b4a0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
1b4b0 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
1b4c0 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
1b4d0 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
1b4e0 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
1b4f0 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
1b500 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
1b510 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
1b520 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
1b530 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
1b540 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
1b550 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
1b560 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
1b570 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
1b580 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
1b590 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
1b5a0 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
1b5b0 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
1b5c0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1b5d0 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
1b5e0 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
1b5f0 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
1b600 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
1b610 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
1b620 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
1b630 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
1b640 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1b650 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
1b660 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
1b670 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
1b680 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
1b690 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
1b6a0 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
1b6b0 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
1b6c0 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
1b6d0 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
1b6e0 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
1b6f0 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
1b700 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
1b710 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
1b720 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
1b730 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
1b740 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1b750 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
1b760 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
1b770 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1b780 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
1b790 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
1b7a0 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
1b7b0 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
1b7c0 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
1b7d0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
1b7e0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
1b7f0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
1b800 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
1b810 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1b820 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
1b830 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1b840 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1b850 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b860 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1b870 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1b880 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
1b890 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
1b8a0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1b8b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1b8c0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
1b8d0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
1b8e0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
1b8f0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
1b900 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
1b910 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
1b920 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
1b930 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
1b940 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
1b950 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
1b960 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
1b970 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
1b980 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
1b990 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
1b9a0 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
1b9b0 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
1b9c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1b9d0 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
1b9e0 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
1b9f0 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
1ba00 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
1ba10 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
1ba20 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
1ba30 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
1ba40 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
1ba50 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1ba60 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
1ba70 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1ba80 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
1ba90 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
1baa0 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
1bab0 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
1bac0 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
1bad0 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
1bae0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
1baf0 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
1bb00 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
1bb10 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
1bb20 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
1bb30 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
1bb40 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
1bb50 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
1bb60 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
1bb70 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
1bb80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74  .int sqlite3_set
1bb90 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
1bba0 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
1bbb0 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
1bbc0 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
1bbd0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1bbe0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1bbf0 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
1bc00 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
1bc10 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1bc20 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
1bc30 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1bc40 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1bc50 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1bc60 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1bc70 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
1bc80 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
1bc90 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
1bca0 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
1bcb0 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
1bcc0 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
1bcd0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1bce0 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
1bcf0 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
1bd00 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
1bd10 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1bd20 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
1bd30 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
1bd40 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1bd50 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
1bd60 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
1bd70 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
1bd80 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f  ed as a [SQLITE_
1bd90 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72  ROLLBACK | retur
1bda0 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20  n code].** from 
1bdb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  the [sqlite3_vta
1bdc0 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
1bdd0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23   interface..*/.#
1bde0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1bdf0 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
1be00 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1be10 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
1be20 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
1be30 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
1be40 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
1be50 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
1be60 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
1be70 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
1be80 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
1be90 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a   Action Codes.**
1bea0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1beb0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1bec0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
1bed0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
1bee0 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
1bef0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
1bf00 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
1bf10 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
1bf20 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
1bf30 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1bf40 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
1bf50 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1bf60 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
1bf70 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
1bf80 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
1bf90 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
1bfa0 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
1bfb0 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
1bfc0 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
1bfd0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
1bfe0 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
1bff0 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
1c000 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
1c010 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
1c020 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
1c030 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
1c040 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
1c050 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
1c060 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
1c070 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
1c080 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
1c090 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
1c0a0 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
1c0b0 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
1c0c0 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
1c0d0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1c0e0 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20  rameter.  ^(The 
1c0f0 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
1c100 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1c110 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
1c120 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
1c130 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
1c140 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
1c150 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
1c160 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72  )^  ^The 6th par
1c170 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1c180 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1c190 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
1c1a0 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
1c1b0 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
1c1c0 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
1c1d0 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
1c1e0 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
1c1f0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
1c200 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1c210 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
1c220 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
1c230 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
1c240 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c250 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c260 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
1c270 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
1c280 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
1c290 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1c2a0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
1c2b0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1c2c0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1c2d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1c2e0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1c2f0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
1c300 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1c310 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1c320 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1c330 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1c340 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
1c350 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1c360 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1c370 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1c380 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1c390 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
1c3a0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1c3b0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1c3c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1c3d0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1c3e0 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
1c3f0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1c400 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1c410 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1c420 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1c430 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
1c440 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1c450 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1c460 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c470 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
1c480 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
1c490 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1c4a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1c4b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c4c0 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
1c4d0 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
1c4e0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1c4f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1c500 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c510 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
1c520 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
1c530 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1c540 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1c550 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c560 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
1c570 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
1c580 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1c590 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1c5a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1c5b0 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
1c5c0 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
1c5d0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1c5e0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1c5f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1c600 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
1c610 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
1c620 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1c630 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1c640 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1c650 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
1c660 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
1c670 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1c680 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1c690 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1c6a0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1c6b0 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
1c6c0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1c6d0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1c6e0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1c6f0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
1c700 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
1c710 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1c720 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1c730 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1c740 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
1c750 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
1c760 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1c770 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1c780 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
1c790 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
1c7a0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1c7b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1c7c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1c7d0 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
1c7e0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
1c7f0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1c800 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1c810 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1c820 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
1c830 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
1c840 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
1c850 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
1c860 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
1c870 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
1c880 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
1c890 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1c8a0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
1c8b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1c8c0 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
1c8d0 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
1c8e0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
1c8f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1c900 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1c910 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
1c920 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
1c930 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
1c940 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1c950 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c960 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
1c970 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
1c980 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1c990 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
1c9a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c9b0 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
1c9c0 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
1c9d0 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
1c9e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1c9f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ca00 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
1ca10 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
1ca20 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
1ca30 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1ca40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ca50 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
1ca60 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
1ca70 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
1ca80 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1ca90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
1caa0 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
1cab0 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
1cac0 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
1cad0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1cae0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
1caf0 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
1cb00 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
1cb10 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1cb20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1cb30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1cb40 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
1cb50 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
1cb60 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1cb70 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1cb80 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1cb90 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
1cba0 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
1cbb0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
1cbc0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1cbd0 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
1cbe0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
1cbf0 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  31   /* NULL    
1cc00 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e          Function
1cc10 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69   Name   */.#defi
1cc20 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f  ne SQLITE_SAVEPO
1cc30 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33  INT            3
1cc40 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
1cc50 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74         Savepoint
1cc60 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e   Name  */.#defin
1cc70 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
1cc80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
1cc90 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
1cca0 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
1ccb0 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
1ccc0 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
1ccd0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1cce0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1ccf0 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
1cd00 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
1cd10 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
1cd20 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
1cd30 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
1cd40 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
1cd50 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
1cd60 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
1cd70 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
1cd80 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
1cd90 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
1cda0 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
1cdb0 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
1cdc0 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
1cdd0 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
1cde0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
1cdf0 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
1ce00 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
1ce10 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
1ce20 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
1ce30 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
1ce40 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
1ce50 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
1ce60 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
1ce70 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
1ce80 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
1ce90 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
1cea0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
1ceb0 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
1cec0 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
1ced0 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
1cee0 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
1cef0 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
1cf00 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
1cf10 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
1cf20 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
1cf30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
1cf40 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1cf50 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1cf60 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
1cf70 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
1cf80 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
1cf90 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65   finishes.  ^The
1cfa0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1cfb0 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
1cfc0 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
1cfd0 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
1cfe0 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
1cff0 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
1d000 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
1d010 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
1d020 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72  to run.  ^The pr
1d030 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  ofile callback.*
1d040 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69  * time is in uni
1d050 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  ts of nanosecond
1d060 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63  s, however the c
1d070 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
1d080 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79  ation.** is only
1d090 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c   capable of mill
1d0a0 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69  isecond resoluti
1d0b0 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65  on so the six le
1d0c0 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a  ast significant.
1d0d0 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65  ** digits in the
1d0e0 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e   time are meanin
1d0f0 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76  gless.  Future v
1d100 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1d110 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69  e.** might provi
1d120 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c  de greater resol
1d130 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f  ution on the pro
1d140 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  filer callback. 
1d150 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
1d160 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69  profile() functi
1d170 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  on is considered
1d180 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
1d190 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20  d is.** subject 
1d1a0 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  to change in fut
1d1b0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1d1c0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20  SQLite..*/.void 
1d1d0 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
1d1e0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78  qlite3*, void(*x
1d1f0 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
1d200 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
1d210 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  );.SQLITE_EXPERI
1d220 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c  MENTAL void *sql
1d230 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
1d240 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
1d250 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
1d260 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
1d270 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
1d280 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1d290 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
1d2a0 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
1d2b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1d2c0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1d2d0 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65  er(D,N,X,P) inte
1d2e0 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65  rface causes the
1d2f0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
1d300 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e  ction X to be in
1d310 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
1d320 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72  ly during long r
1d330 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a  unning calls to.
1d340 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
1d350 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
1d360 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ep()] and [sqlit
1d370 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
1d380 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  for.** database 
1d390 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41  connection D.  A
1d3a0 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
1d3b0 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  r this.** interf
1d3c0 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
1d3d0 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
1d3e0 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
1d3f0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61  y..**.** ^The pa
1d400 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73  rameter P is pas
1d410 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
1d420 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
1d430 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c  r to the .** cal
1d440 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
1d450 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
1d460 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62 65  r N is the numbe
1d470 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61  r of .** [virtua
1d480 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75  l machine instru
1d490 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65  ctions] that are
1d4a0 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65   evaluated betwe
1d4b0 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a  en successive.**
1d4c0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
1d4d0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a  the callback X..
1d4e0 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69  **.** ^Only a si
1d4f0 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61  ngle progress ha
1d500 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66  ndler may be def
1d510 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65  ined at one time
1d520 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73   per.** [databas
1d530 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73  e connection]; s
1d540 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f  etting a new pro
1d550 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
1d560 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64  ncels the.** old
1d570 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20   one.  ^Setting 
1d580 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e  parameter X to N
1d590 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65  ULL disables the
1d5a0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1d5b0 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72  r..** ^The progr
1d5c0 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61  ess handler is a
1d5d0 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20  lso disabled by 
1d5e0 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76  setting N to a v
1d5f0 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61  alue less.** tha
1d600 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  n 1..**.** ^If t
1d610 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
1d620 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
1d630 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
1d640 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
1d650 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
1d660 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
1d670 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
1d680 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
1d690 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
1d6a0 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
1d6b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
1d6c0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
1d6d0 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
1d6e0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
1d6f0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
1d700 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1d710 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1d720 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
1d730 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
1d740 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
1d750 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
1d760 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
1d770 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
1d780 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
1d790 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
1d7a0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
1d7b0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
1d7c0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
1d7d0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  /.void sqlite3_p
1d7e0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1d7f0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
1d800 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
1d810 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1d820 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
1d830 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
1d840 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  nnection.**.** ^
1d850 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
1d860 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
1d870 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73  tabase file as s
1d880 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
1d890 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
1d8a0 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
1d8b0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
1d8c0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1d8d0 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
1d8e0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
1d8f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1d900 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
1d910 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1d920 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
1d930 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1d940 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
1d950 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
1d960 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
1d970 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
1d980 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
1d990 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
1d9a0 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
1d9b0 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
1d9c0 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
1d9d0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
1d9e0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
1d9f0 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
1da00 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
1da10 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
1da20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
1da30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1da40 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
1da50 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
1da60 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1da70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
1da80 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
1da90 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
1daa0 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
1dab0 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
1dac0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
1dad0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
1dae0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
1daf0 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
1db00 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1db10 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
1db20 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
1db30 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
1db40 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
1db50 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
1db60 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
1db70 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
1db80 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
1db90 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
1dba0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
1dbb0 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74  t encoding for t
1dbc0 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  he database will
1dbd0 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20   be UTF-8 if.** 
1dbe0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
1dbf0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
1dc00 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e  2() is called an
1dc10 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74  d.** UTF-16 in t
1dc20 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
1dc30 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f  rder if sqlite3_
1dc40 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64  open16() is used
1dc50 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
1dc60 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
1dc70 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
1dc80 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
1dc90 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
1dca0 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
1dcb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1dcc0 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
1dcd0 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a  e released by.**
1dce0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
1dcf0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
1dd00 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
1dd10 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
1dd20 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1dd30 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65  3_open_v2() inte
1dd40 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
1dd50 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a   sqlite3_open().
1dd60 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
1dd70 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64  t accepts two ad
1dd80 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
1dd90 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
1dda0 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76  al control.** ov
1ddb0 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  er the new datab
1ddc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
1ddd0 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72   ^(The flags par
1dde0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c  ameter to.** sql
1ddf0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63  ite3_open_v2() c
1de00 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a  an take one of.*
1de10 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
1de20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70  three values, op
1de30 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
1de40 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  d with the .** [
1de50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1de60 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
1de70 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b  EN_FULLMUTEX], [
1de80 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
1de90 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51  EDCACHE],.** [SQ
1dea0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
1deb0 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20  ECACHE], and/or 
1dec0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
1ded0 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a  ] flags:)^.**.**
1dee0 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b   <dl>.** ^(<dt>[
1def0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1df00 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ONLY]</dt>.** <d
1df10 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1df20 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64  s opened in read
1df30 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20  -only mode.  If 
1df40 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
1df50 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79  s not.** already
1df60 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
1df70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
1df80 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1df90 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
1dfa0 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  ADWRITE]</dt>.**
1dfb0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1dfc0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1dfd0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
1dfe0 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c  ing if possible,
1dff0 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f   or reading.** o
1e000 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20  nly if the file 
1e010 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
1e020 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
1e030 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20  ing system.  In 
1e040 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74  either.** case t
1e050 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74  he database must
1e060 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
1e070 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  otherwise an err
1e080 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
1e090 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1e0a0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
1e0b0 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
1e0c0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1e0d0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1e0e0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1e0f0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
1e100 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e   and writing, an
1e110 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a  d is created if.
1e120 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61  ** it does not a
1e130 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68  lready exist. Th
1e140 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69  is is the behavi
1e150 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79  or that is alway
1e160 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71  s used for.** sq
1e170 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1e180 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1e190 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  ).</dd>)^.** </d
1e1a0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
1e1b0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
1e1c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1e1d0 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
1e1e0 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
1e1f0 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
1e200 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
1e210 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a  ined with other.
1e220 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1e230 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54  READONLY | SQLIT
1e240 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a  E_OPEN_* bits].*
1e250 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
1e260 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
1e270 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1e280 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1e290 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1e2a0 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
1e2b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1e2c0 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
1e2d0 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
1e2e0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
1e2f0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
1e300 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
1e310 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
1e320 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
1e330 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
1e340 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  e.  ^If the.** [
1e350 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1e360 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1e370 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
1e380 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1e390 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
1e3a0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
1e3b0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
1e3c0 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
1e3d0 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
1e3e0 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
1e3f0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
1e400 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54  tart-time..** ^T
1e410 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1e420 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61  SHAREDCACHE] fla
1e430 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
1e440 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e450 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62   to be.** eligib
1e460 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65  le to use [share
1e470 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72  d cache mode], r
1e480 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1e490 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
1e4a0 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
1e4b0 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
1e4c0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
1e4d0 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e  red_cache()].  ^
1e4e0 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  The.** [SQLITE_O
1e4f0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
1e500 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
1e510 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1e520 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20  ction to not.** 
1e530 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b  participate in [
1e540 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
1e550 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  e] even if it is
1e560 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1e570 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
1e580 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1e590 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68  _open_v2() is th
1e5a0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
1e5b0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1e5c0 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
1e5d0 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
1e5e0 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
1e5f0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65  e that.** the ne
1e600 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
1e610 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ction should use
1e620 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  .  ^If the fourt
1e630 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
1e640 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
1e650 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
1e660 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1e670 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a  object is used..
1e680 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
1e690 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
1e6a0 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69  ry:", then a pri
1e6b0 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20  vate, temporary 
1e6c0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
1e6d0 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64  se.** is created
1e6e0 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
1e6f0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d  ion.  ^This in-m
1e700 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
1e710 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
1e720 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1e730 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
1e740 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
1e750 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1e760 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
1e770 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
1e780 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
1e790 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
1e7a0 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
1e7b0 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
1e7c0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
1e7d0 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
1e7e0 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
1e7f0 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
1e800 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
1e810 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
1e820 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
1e830 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
1e840 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
1e850 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
1e860 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iguity..**.** ^I
1e870 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
1e880 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
1e890 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
1e8a0 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20  e, temporary.** 
1e8b0 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65  on-disk database
1e8c0 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64   will be created
1e8d0 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65  .  ^This private
1e8e0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1e8f0 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
1e900 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f  ly deleted as so
1e910 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61  on as the databa
1e920 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1e930 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   closed..**.** [
1e940 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69  [URI filenames i
1e950 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  n sqlite3_open()
1e960 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e  ]] <h3>URI Filen
1e970 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ames</h3>.**.** 
1e980 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ^If [URI filenam
1e990 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  e] interpretatio
1e9a0 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e  n is enabled, an
1e9b0 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  d the filename a
1e9c0 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e  rgument.** begin
1e9d0 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20  s with "file:", 
1e9e0 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d  then the filenam
1e9f0 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  e is interpreted
1ea00 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a   as a URI. ^URI.
1ea10 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  ** filename inte
1ea20 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
1ea30 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51  abled if the [SQ
1ea40 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
1ea50 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e  lag is.** set in
1ea60 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
1ea70 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1ea80 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66  open_v2(), or if
1ea90 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20   it has.** been 
1eaa0 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79  enabled globally
1eab0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
1eac0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f  TE_CONFIG_URI] o
1ead0 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a  ption with the.*
1eae0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
1eaf0 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62  g()] method or b
1eb00 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  y the [SQLITE_US
1eb10 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74  E_URI] compile-t
1eb20 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41  ime option..** A
1eb30 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
1eb40 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66  ion 3.7.7, URI f
1eb50 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
1eb60 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  tation is turned
1eb70 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75   off.** by defau
1eb80 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72  lt, but future r
1eb90 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
1eba0 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55  e might enable U
1ebb0 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69  RI filename.** i
1ebc0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79  nterpretation by
1ebd0 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22   default.  See "
1ebe0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22  [URI filenames]"
1ebf0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
1ec00 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
1ec10 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61  **.** URI filena
1ec20 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61  mes are parsed a
1ec30 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20  ccording to RFC 
1ec40 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52  3986. ^If the UR
1ec50 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a  I contains an.**
1ec60 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e   authority, then
1ec70 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68   it must be eith
1ec80 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  er an empty stri
1ec90 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67  ng or the string
1eca0 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22   .** "localhost"
1ecb0 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72  . ^If the author
1ecc0 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d  ity is not an em
1ecd0 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c  pty string or "l
1ece0 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a  ocalhost", an .*
1ecf0 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  * error is retur
1ed00 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65  ned to the calle
1ed10 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74  r. ^The fragment
1ed20 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
1ed30 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73  URI, if .** pres
1ed40 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e  ent, is ignored.
1ed50 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
1ed60 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d  ses the path com
1ed70 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52  ponent of the UR
1ed80 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  I as the name of
1ed90 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a   the disk file.*
1eda0 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73  * which contains
1edb0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e   the database. ^
1edc0 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69  If the path begi
1edd0 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68  ns with a '/' ch
1ede0 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65  aracter, .** the
1edf0 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65  n it is interpre
1ee00 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75  ted as an absolu
1ee10 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65  te path. ^If the
1ee20 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62   path does not b
1ee30 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20  egin .** with a 
1ee40 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61  '/' (meaning tha
1ee50 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  t the authority 
1ee60 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74  section is omitt
1ee70 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29  ed from the URI)
1ee80 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74  .** then the pat
1ee90 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
1eea0 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70   as a relative p
1eeb0 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e  ath. .** ^On win
1eec0 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20  dows, the first 
1eed0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20  component of an 
1eee0 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a  absolute path .*
1eef0 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65  * is a drive spe
1ef00 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e  cification (e.g.
1ef10 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b   "C:")..**.** [[
1ef20 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70  core URI query p
1ef30 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54  arameters]].** T
1ef40 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
1ef50 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20  nt of a URI may 
1ef60 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65  contain paramete
1ef70 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  rs that are inte
1ef80 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65  rpreted.** eithe
1ef90 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65  r by SQLite itse
1efa0 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53  lf, or by a [VFS
1efb0 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d   | custom VFS im
1efc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a  plementation]..*
1efd0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72  * SQLite interpr
1efe0 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ets the followin
1eff0 67 20 74 68 72 65 65 20 71 75 65 72 79 20 70 61  g three query pa
1f000 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20  rameters:.**.** 
1f010 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  <ul>.**   <li> <
1f020 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20  b>vfs</b>: ^The 
1f030 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20  "vfs" parameter 
1f040 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73  may be used to s
1f050 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20  pecify the name 
1f060 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20  of.**     a VFS 
1f070 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76  object that prov
1f080 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ides the operati
1f090 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
1f0a0 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a  ace that should.
1f0b0 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74  **     be used t
1f0c0 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
1f0d0 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69  abase file on di
1f0e0 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74  sk. ^If this opt
1f0f0 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a  ion is set to.**
1f100 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74       an empty st
1f110 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74  ring the default
1f120 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75   VFS object is u
1f130 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67  sed. ^Specifying
1f140 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20   an unknown.**  
1f150 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72     VFS is an err
1f160 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  or. ^If sqlite3_
1f170 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
1f180 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70  d and the vfs op
1f190 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70  tion is.**     p
1f1a0 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65  resent, then the
1f1b0 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62   VFS specified b
1f1c0 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b  y the option tak
1f1d0 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76  es precedence ov
1f1e0 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61  er.**     the va
1f1f0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
1f200 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1f210 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
1f220 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
1f230 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62   <li> <b>mode</b
1f240 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61  >: ^(The mode pa
1f250 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
1f260 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f  et to either "ro
1f270 22 2c 20 22 72 77 22 20 6f 72 0a 2a 2a 20 20 20  ", "rw" or.**   
1f280 20 20 22 72 77 63 22 2e 20 41 74 74 65 6d 70 74    "rwc". Attempt
1f290 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f  ing to set it to
1f2a0 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65   any other value
1f2b0 20 69 73 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20   is an error)^. 
1f2c0 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22  .**     ^If "ro"
1f2d0 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
1f2e0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
1f2f0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
1f300 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20  ead-only .**    
1f310 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73   access, just as
1f320 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
1f330 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66  OPEN_READONLY] f
1f340 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74  lag had been set
1f350 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20   in the .**     
1f360 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
1f370 6f 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  o sqlite3_prepar
1f380 65 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20  e_v2(). ^If the 
1f390 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73  mode option is s
1f3a0 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72  et to .**     "r
1f3b0 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  w", then the dat
1f3c0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1f3d0 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28  for read-write (
1f3e0 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20  but not create) 
1f3f0 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
1f400 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45  as if SQLITE_OPE
1f410 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74  N_READWRITE (but
1f420 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e   not SQLITE_OPEN
1f430 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a  _CREATE) had .**
1f440 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e       been set. ^
1f450 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65  Value "rwc" is e
1f460 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
1f470 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20  ting both .**   
1f480 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45    SQLITE_OPEN_RE
1f490 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49  ADWRITE and SQLI
1f4a0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20  TE_OPEN_CREATE. 
1f4b0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
1f4c0 5f 76 32 28 29 20 69 73 20 0a 2a 2a 20 20 20 20  _v2() is .**    
1f4d0 20 75 73 65 64 2c 20 69 74 20 69 73 20 61 6e 20   used, it is an 
1f4e0 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79  error to specify
1f4f0 20 61 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65   a value for the
1f500 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
1f510 74 68 61 74 20 69 73 20 0a 2a 2a 20 20 20 20 20  that is .**     
1f520 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65  less restrictive
1f530 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69   than that speci
1f540 66 69 65 64 20 62 79 20 74 68 65 20 66 6c 61 67  fied by the flag
1f550 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
1f560 74 68 69 72 64 20 0a 2a 2a 20 20 20 20 20 70 61  third .**     pa
1f570 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 20  rameter..**.**  
1f580 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f   <li> <b>cache</
1f590 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70  b>: ^The cache p
1f5a0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
1f5b0 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73  set to either "s
1f5c0 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20  hared" or.**    
1f5d0 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74   "private". ^Set
1f5e0 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72  ting it to "shar
1f5f0 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ed" is equivalen
1f600 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
1f610 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
1f620 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
1f630 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73  bit in the flags
1f640 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
1f650 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74   to.**     sqlit
1f660 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53  e3_open_v2(). ^S
1f670 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65  etting the cache
1f680 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70   parameter to "p
1f690 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20  rivate" is .**  
1f6a0 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f     equivalent to
1f6b0 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c   setting the SQL
1f6c0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1f6d0 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20  CACHE bit..**   
1f6e0 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70    ^If sqlite3_op
1f6f0 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
1f700 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20  and the "cache" 
1f710 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65  parameter is pre
1f720 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61  sent in.**     a
1f730 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69   URI filename, i
1f740 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64  ts value overrid
1f750 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 75 72  es any behaviour
1f760 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65   requested by se
1f770 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c  tting.**     SQL
1f780 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1f790 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f  CACHE or SQLITE_
1f7a0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
1f7b0 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a   flag..** </ul>.
1f7c0 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e  **.** ^Specifyin
1f7d0 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72  g an unknown par
1f7e0 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75  ameter in the qu
1f7f0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
1f800 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e   a URI is not an
1f810 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75  .** error.  Futu
1f820 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1f830 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65  QLite might unde
1f840 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61  rstand additiona
1f850 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  l query.** param
1f860 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75  eters.  See "[qu
1f870 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77  ery parameters w
1f880 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e  ith special mean
1f890 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20  ing to SQLite]" 
1f8a0 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
1f8b0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
1f8c0 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
1f8d0 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c  ame examples]] <
1f8e0 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  h3>URI filename 
1f8f0 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a  examples</h3>.**
1f900 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
1f910 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74  r="1" align=cent
1f920 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35  er cellpadding=5
1f930 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52  >.** <tr><th> UR
1f940 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e  I filenames <th>
1f950 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e   Results.** <tr>
1f960 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
1f970 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
1f980 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c      Open the fil
1f990 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
1f9a0 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
1f9b0 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tory..** <tr><td
1f9c0 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
1f9d0 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a  d/data.db<br>.**
1f9e0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
1f9f0 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  //home/fred/data
1fa00 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20  .db <br> .**    
1fa10 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63        file://loc
1fa20 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64  alhost/home/fred
1fa30 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74  /data.db <br> <t
1fa40 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
1fa50 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  Open the databas
1fa60 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  e file "/home/fr
1fa70 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20  ed/data.db"..** 
1fa80 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f  <tr><td> file://
1fa90 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72  darkstar/home/fr
1faa0 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  ed/data.db <td> 
1fab0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
1fac0 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72  error. "darkstar
1fad0 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67  " is not a recog
1fae0 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e  nized authority.
1faf0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c  .** <tr><td styl
1fb00 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e  e="white-space:n
1fb10 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20  owrap"> .**     
1fb20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f       file:///C:/
1fb30 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25  Documents%20and%
1fb40 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f  20Settings/fred/
1fb50 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a  Desktop/data.db.
1fb60 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64  **     <td> Wind
1fb70 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74  ows only: Open t
1fb80 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
1fb90 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b  " on fred's desk
1fba0 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20  top on drive.** 
1fbb0 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74           C:. Not
1fbc0 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65  e that the %20 e
1fbd0 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20  scaping in this 
1fbe0 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73  example is not s
1fbf0 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20  trictly .**     
1fc00 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d       necessary -
1fc10 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72   space character
1fc20 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69  s can be used li
1fc30 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20  terally.**      
1fc40 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e      in URI filen
1fc50 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ames..** <tr><td
1fc60 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
1fc70 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69  ode=ro&cache=pri
1fc80 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  vate <td> .**   
1fc90 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
1fca0 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
1fcb0 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
1fcc0 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ory for read-onl
1fcd0 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20  y access..**    
1fce0 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73        Regardless
1fcf0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
1fd00 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20  ot shared-cache 
1fd10 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20  mode is enabled 
1fd20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  by.**          d
1fd30 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72  efault, use a pr
1fd40 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20  ivate cache..** 
1fd50 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
1fd60 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
1fd70 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b  ?vfs=unix-nolock
1fd80 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20   <td>.**        
1fd90 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f    Open file "/ho
1fda0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
1fdb0 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61  . Use the specia
1fdc0 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f  l VFS "unix-nolo
1fdd0 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ck"..** <tr><td>
1fde0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
1fdf0 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e  de=readonly <td>
1fe00 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
1fe10 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c   error. "readonl
1fe20 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69  y" is not a vali
1fe30 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65  d option for the
1fe40 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65   "mode" paramete
1fe50 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  r..** </table>.*
1fe60 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65  *.** ^URI hexade
1fe70 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
1fe80 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65  uences (%HH) are
1fe90 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69   supported withi
1fea0 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a  n the path and.*
1feb0 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  * query componen
1fec0 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68  ts of a URI. A h
1fed0 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
1fee0 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69  e sequence consi
1fef0 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63  sts of a.** perc
1ff00 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d  ent sign - "%" -
1ff10 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61   followed by exa
1ff20 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63  ctly two hexadec
1ff30 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20  imal digits .** 
1ff40 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63  specifying an oc
1ff50 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f  tet value. ^Befo
1ff60 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71  re the path or q
1ff70 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
1ff80 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65  of a.** URI file
1ff90 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72  name are interpr
1ffa0 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65  eted, they are e
1ffb0 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46  ncoded using UTF
1ffc0 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68  -8 and all .** h
1ffd0 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
1ffe0 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c  e sequences repl
1fff0 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65  aced by a single
20000 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67   byte containing
20010 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f   the.** correspo
20020 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20  nding octet. If 
20030 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e  this process gen
20040 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69  erates an invali
20050 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  d UTF-8 encoding
20060 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73  ,.** the results
20070 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
20080 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
20090 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c   Windows users:<
200a0 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e  /b>  The encodin
200b0 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66  g used for the f
200c0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
200d0 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  .** of sqlite3_o
200e0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
200f0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74  3_open_v2() must
20100 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77   be UTF-8, not w
20110 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70  hatever.** codep
20120 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  age is currently
20130 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e   defined.  Filen
20140 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ames containing 
20150 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a  international.**
20160 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74   characters must
20170 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
20180 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20   UTF-8 prior to 
20190 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74  passing them int
201a0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
201b0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
201c0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e 74  pen_v2()..*/.int
201d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20   sqlite3_open(. 
201e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
201f0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
20200 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
20210 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
20220 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
20230 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
20240 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
20250 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
20260 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f  en16(.  const vo
20270 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  id *filename,   
20280 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
20290 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f  name (UTF-16) */
202a0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
202b0 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
202c0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
202d0 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
202e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20  lite3_open_v2(. 
202f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
20300 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
20310 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
20320 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
20330 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20  e3 **ppDb,      
20340 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
20350 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  e db handle */. 
20360 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20   int flags,     
20370 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67           /* Flag
20380 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  s */.  const cha
20390 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f  r *zVfs        /
203a0 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f  * Name of VFS mo
203b0 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29  dule to use */.)
203c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
203d0 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73  F: Obtain Values
203e0 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74   For URI Paramet
203f0 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ers.**.** These 
20400 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74  are utility rout
20410 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20  ines, useful to 
20420 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
20430 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a  ons, that check.
20440 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64  ** to see if a d
20450 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73  atabase file was
20460 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74   a URI that cont
20470 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63  ained a specific
20480 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d   query .** param
20490 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20  eter, and if so 
204a0 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75  obtains the valu
204b0 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20  e of that query 
204c0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
204d0 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74   If F is the dat
204e0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70  abase filename p
204f0 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e  ointer passed in
20500 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d  to the xOpen() m
20510 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56  ethod of .** a V
20520 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
20530 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73  n when the flags
20540 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
20550 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72  pen() has one or
20560 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65   .** more of the
20570 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
20580 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  I] or [SQLITE_OP
20590 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73  EN_MAIN_DB] bits
205a0 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73   set and.** P is
205b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
205c0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
205d0 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
205e0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
205f0 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65  F,P) returns the
20600 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a   value of the P.
20610 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20  ** parameter if 
20620 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e  it exists or a N
20630 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50  ULL pointer if P
20640 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72   does not appear
20650 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20   as a .** query 
20660 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20  parameter on F. 
20670 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79   If P is a query
20680 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a   parameter of F.
20690 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63  ** has no explic
206a0 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73  it value, then s
206b0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
206c0 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
206d0 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
206e0 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  o an empty strin
206f0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  g..**.** The sql
20700 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
20710 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
20720 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69  assumes that P i
20730 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70  s a boolean.** p
20740 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
20750 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72  urns true (1) or
20760 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72   false (0) accor
20770 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75  ding to the valu
20780 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20  e.** of P.  The 
20790 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
207a0 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
207b0 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ne returns true 
207c0 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61  (1) if the.** va
207d0 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72  lue of query par
207e0 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
207f0 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22  of "yes", "true"
20800 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79  , or "on" in any
20810 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74  .** case or if t
20820 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20  he value begins 
20830 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  with a non-zero 
20840 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a  number.  The .**
20850 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
20860 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
20870 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c  ines returns fal
20880 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61  se (0) if the va
20890 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20  lue of.** query 
208a0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
208b0 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c  ne of "no", "fal
208c0 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e  se", or "off" in
208d0 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20   any case or.** 
208e0 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67  if the value beg
208f0 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72  ins with a numer
20900 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69  ic zero.  If P i
20910 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a  s not a query.**
20920 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20   parameter on F 
20930 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
20940 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74  of P is does not
20950 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68   match any of th
20960 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e  e.** above, then
20970 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
20980 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
20990 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a  rns (B!=0)..**.*
209a0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72  * The sqlite3_ur
209b0 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72  i_int64(F,P,D) r
209c0 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20  outine converts 
209d0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
209e0 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20  nto a.** 64-bit 
209f0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
20a00 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20  nd returns that 
20a10 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66  integer, or D if
20a20 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65   P does not.** e
20a30 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61  xist.  If the va
20a40 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65  lue of P is some
20a50 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
20a60 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
20a70 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74  n.** zero is ret
20a80 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66  urned..** .** If
20a90 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   F is a NULL poi
20aa0 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74  nter, then sqlit
20ab0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
20ac0 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55  (F,P) returns NU
20ad0 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  LL and.** sqlite
20ae0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
20af0 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20  P,B) returns B. 
20b00 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e   If F is not a N
20b10 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a  ULL pointer and.
20b20 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  ** is not a data
20b30 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61  base file pathna
20b40 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  me pointer that 
20b50 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e  SQLite passed in
20b60 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20  to the xOpen.** 
20b70 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  VFS method, then
20b80 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
20b90 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
20ba0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
20bb0 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73  robably.** undes
20bc0 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74  irable..*/.const
20bd0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75   char *sqlite3_u
20be0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e  ri_parameter(con
20bf0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
20c00 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  me, const char *
20c10 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c  zParam);.int sql
20c20 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
20c30 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
20c40 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  le, const char *
20c50 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66  zParam, int bDef
20c60 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69  ault);.sqlite3_i
20c70 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69  nt64 sqlite3_uri
20c80 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61  _int64(const cha
20c90 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  r*, const char*,
20ca0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
20cb0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
20cc0 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41  F: Error Codes A
20cd0 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a  nd Messages.**.*
20ce0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
20cf0 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61  rrcode() interfa
20d00 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
20d10 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63  umeric [result c
20d20 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
20d30 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
20d40 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72  ] for the most r
20d50 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c  ecent failed sql
20d60 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a  ite3_* API call.
20d70 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
20d80 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
20d90 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61  onnection]. If a
20da0 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20   prior API call 
20db0 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68  failed.** but th
20dc0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50  e most recent AP
20dd0 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64  I call succeeded
20de0 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
20df0 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  ue from.** sqlit
20e00 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20  e3_errcode() is 
20e10 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  undefined.  ^The
20e20 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
20e30 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69  d_errcode().** i
20e40 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20  nterface is the 
20e50 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74  same except that
20e60 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
20e70 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65  ns the .** [exte
20e80 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
20e90 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65  ] even when exte
20ea0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
20eb0 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
20ec0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
20ed0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61  lite3_errmsg() a
20ee0 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  nd sqlite3_errms
20ef0 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67  g16() return Eng
20f00 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a  lish-language.**
20f10 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72   text that descr
20f20 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20  ibes the error, 
20f30 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
20f40 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63  or UTF-16 respec
20f50 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d  tively..** ^(Mem
20f60 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
20f70 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
20f80 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
20f90 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54  internally..** T
20fa0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
20fb0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
20fc0 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65  worry about free
20fd0 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a  ing the result..
20fe0 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
20ff0 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67  error string mig
21000 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ht be overwritte
21010 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
21020 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e   by.** subsequen
21030 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72  t calls to other
21040 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
21050 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a  e functions.)^.*
21060 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65  *.** When the se
21070 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
21080 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20  ing mode] is in 
21090 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65  use, it might be
210a0 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61   the.** case tha
210b0 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  t a second error
210c0 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70   occurs on a sep
210d0 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20  arate thread in 
210e0 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74  between.** the t
210f0 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74  ime of the first
21100 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63   error and the c
21110 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74  all to these int
21120 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e  erfaces..** When
21130 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74   that happens, t
21140 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20  he second error 
21150 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64  will be reported
21160 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20   since these.** 
21170 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79  interfaces alway
21180 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73  s report the mos
21190 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e  t recent result.
211a0 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68    To avoid.** th
211b0 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20  is, each thread 
211c0 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75  can obtain exclu
211d0 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20  sive use of the 
211e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
211f0 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e  tion] D.** by in
21200 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
21210 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71  mutex_enter]([sq
21220 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
21230 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e  D)) before begin
21240 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44  ning.** to use D
21250 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73   and invoking [s
21260 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
21270 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  ve]([sqlite3_db_
21280 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72  mutex](D)) after
21290 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f  .** all calls to
212a0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
212b0 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20  listed here are 
212c0 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a  completed..**.**
212d0 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65   If an interface
212e0 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49   fails with SQLI
212f0 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20  TE_MISUSE, that 
21300 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66  means the interf
21310 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b  ace.** was invok
21320 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62  ed incorrectly b
21330 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
21340 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65  n.  In that case
21350 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63  , the.** error c
21360 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20  ode and message 
21370 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62  may or may not b
21380 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  e set..*/.int sq
21390 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71  lite3_errcode(sq
213a0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20  lite3 *db);.int 
213b0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
213c0 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
213d0 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61   *db);.const cha
213e0 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
213f0 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  g(sqlite3*);.con
21400 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
21410 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
21420 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
21430 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d  3REF: SQL Statem
21440 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  ent Object.** KE
21450 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65  YWORDS: {prepare
21460 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72  d statement} {pr
21470 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21480 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
21490 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
214a0 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
214b0 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
214c0 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  ement..** This o
214d0 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73  bject is various
214e0 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70  ly known as a "p
214f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21500 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70  t" or a.** "comp
21510 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
21520 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73  nt" or simply as
21530 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a   a "statement"..
21540 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f  **.** The life o
21550 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  f a statement ob
21560 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68  ject goes someth
21570 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ing like this:.*
21580 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
21590 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a  > Create the obj
215a0 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
215b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
215c0 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a   or a related.**
215d0 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a        function..
215e0 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c  ** <li> Bind val
215f0 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72  ues to [host par
21600 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74  ameters] using t
21610 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
21620 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65  *().**      inte
21630 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20  rfaces..** <li> 
21640 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63  Run the SQL by c
21650 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
21660 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d  step()] one or m
21670 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
21680 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61  i> Reset the sta
21690 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
216a0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
216b0 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20  hen go back.**  
216c0 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20      to step 2.  
216d0 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20  Do this zero or 
216e0 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
216f0 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20  li> Destroy the 
21700 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
21710 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
21720 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  ]..** </ol>.**.*
21730 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d  * Refer to docum
21740 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  entation on indi
21750 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61  vidual methods a
21760 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f  bove for additio
21770 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
21780 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
21790 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74  truct sqlite3_st
217a0 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b  mt sqlite3_stmt;
217b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
217c0 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74  : Run-time Limit
217d0 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  s.**.** ^(This i
217e0 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20  nterface allows 
217f0 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69  the size of vari
21800 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74  ous constructs t
21810 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20  o be limited.** 
21820 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  on a connection 
21830 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  by connection ba
21840 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20  sis.  The first 
21850 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
21860 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
21870 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20  nnection] whose 
21880 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73  limit is to be s
21890 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20  et or queried.  
218a0 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
218b0 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f  rameter is one o
218c0 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74  f the [limit cat
218d0 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65  egories] that de
218e0 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20  fine a.** class 
218f0 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  of constructs to
21900 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64   be size limited
21910 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72  .  The third par
21920 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
21930 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74   new limit for t
21940 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e  hat construct.)^
21950 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
21960 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65  ew limit is a ne
21970 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74  gative number, t
21980 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68  he limit is unch
21990 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20  anged..** ^(For 
219a0 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67  each limit categ
219b0 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ory SQLITE_LIMIT
219c0 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65  _<i>NAME</i> the
219d0 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
219e0 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
219f0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61   bound].** set a
21a00 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62  t compile-time b
21a10 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73  y a C preprocess
21a20 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a  or macro called.
21a30 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c  ** [limits | SQL
21a40 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c  ITE_MAX_<i>NAME<
21a50 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  /i>]..** (The "_
21a60 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
21a70 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
21a80 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a  o "_MAX_".))^.**
21a90 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e   ^Attempts to in
21aa0 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
21ab0 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
21ac0 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
21ad0 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
21ae0 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
21af0 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a  upper bound..**.
21b00 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
21b10 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
21b20 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63   the limit was c
21b30 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20  hanged, the .** 
21b40 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
21b50 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
21b60 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61  rns the prior va
21b70 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
21b80 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20  ..** ^Hence, to 
21b90 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74  find the current
21ba0 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69   value of a limi
21bb0 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69  t without changi
21bc0 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79  ng it,.** simply
21bd0 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74   invoke this int
21be0 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20  erface with the 
21bf0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
21c00 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a  set to -1..**.**
21c10 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73   Run-time limits
21c20 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
21c30 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61  r use in applica
21c40 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67  tions that manag
21c50 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20  e.** both their 
21c60 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  own internal dat
21c70 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64  abase and also d
21c80 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72  atabases that ar
21c90 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20  e controlled.** 
21ca0 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74  by untrusted ext
21cb0 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20  ernal sources.  
21cc0 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69  An example appli
21cd0 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  cation might be 
21ce0 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72  a.** web browser
21cf0 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
21d00 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
21d10 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
21d20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
21d30 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
21d40 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
21d50 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
21d60 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
21d70 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
21d80 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
21d90 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
21da0 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
21db0 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
21dc0 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
21dd0 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
21de0 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
21df0 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
21e00 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
21e10 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
21e20 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
21e30 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
21e40 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
21e50 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
21e60 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
21e70 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
21e80 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
21e90 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
21ea0 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
21eb0 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
21ec0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
21ed0 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
21ee0 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
21ef0 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
21f00 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
21f10 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
21f20 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
21f30 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
21f40 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
21f50 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
21f60 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69  e releases..*/.i
21f70 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
21f80 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
21f90 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
21fa0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21fb0 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
21fc0 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
21fd0 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
21fe0 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
21ff0 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
22000 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
22010 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
22020 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
22030 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
22040 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
22050 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
22060 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
22070 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
22080 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
22090 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
220a0 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
220b0 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
220c0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
220d0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
220e0 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
220f0 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
22100 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
22110 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
22120 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
22130 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
22140 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
22150 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
22160 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
22170 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
22180 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
22190 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
221a0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d  MIT_SQL_LENGTH]]
221b0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
221c0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
221d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
221e0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
221f0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
22200 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
22210 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
22220 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d  TE_LIMIT_COLUMN]
22230 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
22240 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
22250 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
22260 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
22270 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
22280 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
22290 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
222a0 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
222b0 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
222c0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
222d0 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
222e0 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
222f0 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
22300 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  clause.</dd>)^.*
22310 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
22320 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d  MIT_EXPR_DEPTH]]
22330 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
22340 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
22350 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
22360 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
22370 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
22380 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
22390 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
223a0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
223b0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20  MPOUND_SELECT]] 
223c0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
223d0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
223e0 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
223f0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
22400 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
22410 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
22420 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
22430 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
22440 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d  _LIMIT_VDBE_OP]]
22450 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
22460 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
22470 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
22480 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
22490 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
224a0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
224b0 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
224c0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
224d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
224e0 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f  This limit is no
224f0 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65  t currently.** e
22500 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20  nforced, though 
22510 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64  that might be ad
22520 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ded in some futu
22530 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
22540 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a   SQLite.</dd>)^.
22550 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
22560 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
22570 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  G]] ^(<dt>SQLITE
22580 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
22590 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
225a0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
225b0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
225c0 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
225d0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
225e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
225f0 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  HED]] ^(<dt>SQLI
22600 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
22610 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
22620 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
22630 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
22640 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
22650 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
22660 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
22670 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
22680 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  TH]].** ^(<dt>SQ
22690 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
226a0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
226b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
226c0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
226d0 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
226e0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
226f0 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
22700 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
22710 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
22720 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
22730 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c  _NUMBER]].** ^(<
22740 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
22750 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
22760 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
22770 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
22780 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
22790 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
227a0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
227b0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
227c0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
227d0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
227e0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
227f0 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
22800 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
22810 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
22820 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
22830 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  d>)^.** </dl>.*/
22840 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22850 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
22860 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22870 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
22880 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
22890 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
228a0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
228b0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
228c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
228d0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
228e0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
228f0 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
22900 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
22910 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
22920 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
22930 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
22940 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
22950 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
22960 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
22970 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
22980 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
22990 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
229a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
229b0 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
229c0 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
229d0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
229e0 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
229f0 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
22a00 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
22a10 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
22a20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
22a30 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
22a40 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20  TRIGGER_DEPTH   
22a50 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a           10../*.
22a60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
22a70 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
22a80 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f  atement.** KEYWO
22a90 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
22aa0 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
22ab0 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
22ac0 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20  n SQL query, it 
22ad0 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f  must first be co
22ae0 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79  mpiled into a by
22af0 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72  te-code.** progr
22b00 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  am using one of 
22b10 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
22b20 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
22b30 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
22b40 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
22b50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
22b60 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
22b70 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
22b80 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
22b90 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
22ba0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a  3_open_v2()] or.
22bb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
22bc0 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61  16()].  The data
22bd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
22be0 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
22bf0 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  en closed..**.**
22c00 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
22c10 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
22c20 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
22c30 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
22c40 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
22c50 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
22c60 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
22c70 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
22c80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
22c90 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
22ca0 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
22cb0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
22cc0 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
22cd0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
22ce0 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a  .** use UTF-16..
22cf0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42  **.** ^If the nB
22d00 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  yte argument is 
22d10 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20  less than zero, 
22d20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61  then zSql is rea
22d30 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66  d up to the.** f
22d40 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
22d50 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20  ator. ^If nByte 
22d60 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
22d70 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20   then it is the 
22d80 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65  maximum.** numbe
22d90 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64  r of  bytes read
22da0 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68   from zSql.  ^Wh
22db0 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  en nByte is non-
22dc0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a  negative, the.**
22dd0 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64   zSql string end
22de0 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20  s at either the 
22df0 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20  first '\000' or 
22e00 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74  '\u0000' charact
22e10 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79  er or.** the nBy
22e20 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63  te-th byte, whic
22e30 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
22e40 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  t. If the caller
22e50 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74   knows.** that t
22e60 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
22e70 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
22e80 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65  ated, then there
22e90 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70   is a small.** p
22ea0 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
22eb0 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65  tage to be gaine
22ec0 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20  d by passing an 
22ed0 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
22ee0 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c  that.** is equal
22ef0 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
22f00 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69  f bytes in the i
22f10 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69  nput string <i>i
22f20 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20  ncluding</i>.** 
22f30 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  the nul-terminat
22f40 6f 72 20 62 79 74 65 73 20 61 73 20 74 68 69 73  or bytes as this
22f50 20 73 61 76 65 73 20 53 51 4c 69 74 65 20 66 72   saves SQLite fr
22f60 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20  om having to.** 
22f70 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74  make a copy of t
22f80 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
22f90 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69  .**.** ^If pzTai
22fa0 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  l is not NULL th
22fb0 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
22fc0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
22fd0 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a  he first byte.**
22fe0 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
22ff0 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
23000 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
23010 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
23020 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c  s only.** compil
23030 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74  e the first stat
23040 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
23050 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
23060 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a  t pointing to.**
23070 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e   what remains un
23080 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
23090 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74  ^*ppStmt is left
230a0 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
230b0 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
230c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
230d0 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
230e0 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
230f0 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49  te3_step()].  ^I
23100 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
23110 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
23120 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
23130 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74   ^If the input t
23140 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ext contains no 
23150 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
23160 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a  t is an empty.**
23170 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d   string or a com
23180 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74  ment) then *ppSt
23190 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c  mt is set to NUL
231a0 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e  L..** The callin
231b0 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
231c0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
231d0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
231e0 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
231f0 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
23200 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
23210 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
23220 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
23230 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f  ** ppStmt may no
23240 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  t be NULL..**.**
23250 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68   ^On success, th
23260 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
23270 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f  e() family of ro
23280 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
23290 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74  QLITE_OK];.** ot
232a0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
232b0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
232c0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
232d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
232e0 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
232f0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
23300 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
23310 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
23320 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
23330 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
23340 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
23350 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
23360 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
23370 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
23380 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
23390 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68  raged..** ^In th
233a0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
233b0 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
233c0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
233d0 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
233e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
233f0 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
23400 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
23410 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
23420 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73   text. This caus
23430 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  es the [sqlite3_
23440 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63  step()] interfac
23450 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64  e to.** behave d
23460 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68  ifferently in th
23470 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ree ways:.**.** 
23480 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  <ol>.** <li>.** 
23490 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  ^If the database
234a0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
234b0 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
234c0 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
234d0 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
234e0 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
234f0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
23500 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
23510 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
23520 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
23530 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
23540 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a  run it again..**
23550 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
23560 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72  >.** ^When an er
23570 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c  ror occurs, [sql
23580 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
23590 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
235a0 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20  the detailed.** 
235b0 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72  [error codes] or
235c0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
235d0 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c   codes].  ^The l
235e0 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77  egacy behavior w
235f0 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69  as that.** [sqli
23600 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
23610 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
23620 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f  generic [SQLITE_
23630 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f  ERROR] result co
23640 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70  de.** and the ap
23650 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20  plication would 
23660 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
23670 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73  econd call to [s
23680 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a  qlite3_reset()].
23690 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  ** in order to f
236a0 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
236b0 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
236c0 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68  problem. With th
236d0 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a  e "v2" prepare.*
236e0 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  * interfaces, th
236f0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
23700 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
23710 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  r is returned im
23720 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
23730 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
23740 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
23750 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74  ic value bound t
23760 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68  o [parameter | h
23770 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69  ost parameter] i
23780 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20  n the .** WHERE 
23790 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66  clause might inf
237a0 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63  luence the choic
237b0 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
237c0 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  for a statement,
237d0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61  .** then the sta
237e0 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61  tement will be a
237f0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
23800 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74  ompiled, as if t
23810 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a  here had been .*
23820 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  * a schema chang
23830 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  e, on the first 
23840 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
23850 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67  ] call following
23860 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74   any change.** t
23870 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  o the [sqlite3_b
23880 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69  ind_text | bindi
23890 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61  ngs] of that [pa
238a0 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54  rameter]. .** ^T
238b0 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
238c0 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73  e of WHERE-claus
238d0 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69  e [parameter] mi
238e0 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
238f0 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20  e .** choice of 
23900 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68  query plan if th
23910 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  e parameter is t
23920 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64  he left-hand sid
23930 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a  e of a [LIKE].**
23940 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61   or [GLOB] opera
23950 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61  tor or if the pa
23960 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61  rameter is compa
23970 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65  red to an indexe
23980 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20  d column.** and 
23990 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  the [SQLITE_ENAB
239a0 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c  LE_STAT3] compil
239b0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
239c0 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65   enabled..** the
239d0 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f   .** </li>.** </
239e0 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ol>.*/.int sqlit
239f0 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
23a00 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
23a10 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
23a20 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
23a30 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
23a40 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
23a50 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
23a60 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
23a70 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
23a80 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
23a90 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
23aa0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
23ab0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
23ac0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
23ad0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
23ae0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
23af0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
23b00 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
23b10 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
23b20 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
23b30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
23b40 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
23b50 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
23b60 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
23b70 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
23b80 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
23b90 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
23ba0 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
23bb0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
23bc0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
23bd0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
23be0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
23bf0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
23c00 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
23c10 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
23c20 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
23c30 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
23c40 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
23c50 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
23c60 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
23c70 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
23c80 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
23c90 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
23ca0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
23cb0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
23cc0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
23cd0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
23ce0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
23cf0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
23d00 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
23d10 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
23d20 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
23d30 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
23d40 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
23d50 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
23d60 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
23d70 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
23d80 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
23d90 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
23da0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
23db0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
23dc0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
23dd0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
23de0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
23df0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
23e00 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
23e10 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
23e20 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
23e30 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
23e40 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
23e50 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
23e60 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
23e70 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
23e80 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
23e90 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
23ea0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
23eb0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
23ec0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
23ed0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
23ee0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
23ef0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
23f00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23f10 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
23f20 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e  ment SQL.**.** ^
23f30 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
23f40 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
23f50 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63  trieve a saved c
23f60 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69  opy of the origi
23f70 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  nal.** SQL text 
23f80 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61  used to create a
23f90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23fa0 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74  ment] if that st
23fb0 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63  atement was.** c
23fc0 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
23fd0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
23fe0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
23ff0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
24000 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  6_v2()]..*/.cons
24010 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
24020 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
24030 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
24040 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
24050 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
24060 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20  tatement Writes 
24070 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a  The Database.**.
24080 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
24090 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29  stmt_readonly(X)
240a0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
240b0 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
240c0 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  o) if.** and onl
240d0 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72  y if the [prepar
240e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
240f0 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20  makes no direct 
24100 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68  changes to.** th
24110 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
24120 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
24130 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
24140 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
24150 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
24160 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75  ns] or.** [virtu
24170 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74  al tables] might
24180 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
24190 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20  base indirectly 
241a0 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74  as a side effect
241b0 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .  .** ^(For exa
241c0 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c  mple, if an appl
241d0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20  ication defines 
241e0 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c  a function "eval
241f0 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c  ()" that .** cal
24200 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ls [sqlite3_exec
24210 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  ()], then the fo
24220 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74  llowing SQL stat
24230 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63  ement would.** c
24240 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
24250 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20  se file through 
24260 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a  side-effects:.**
24270 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
24280 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45  <pre>.**    SELE
24290 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20  CT eval('DELETE 
242a0 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74  FROM t1') FROM t
242b0 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  2;.** </pre></bl
242c0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
242d0 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20  But because the 
242e0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
242f0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nt does not chan
24300 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
24310 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79  file.** directly
24320 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  , sqlite3_stmt_r
24330 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20  eadonly() would 
24340 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75  still return tru
24350 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e  e.)^.**.** ^Tran
24360 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20  saction control 
24370 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20  statements such 
24380 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d  as [BEGIN], [COM
24390 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d  MIT], [ROLLBACK]
243a0 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d  ,.** [SAVEPOINT]
243b0 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20  , and [RELEASE] 
243c0 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74  cause sqlite3_st
243d0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
243e0 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a   return true,.**
243f0 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65   since the state
24400 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
24410 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   do not actually
24420 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
24430 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68  base but.** rath
24440 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20  er they control 
24450 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68  the timing of wh
24460 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65  en other stateme
24470 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a  nts modify the .
24480 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54  ** database.  ^T
24490 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20  he [ATTACH] and 
244a0 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65  [DETACH] stateme
244b0 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a  nts also cause.*
244c0 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
244d0 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
244e0 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20  urn true since, 
244f0 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74  while those stat
24500 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65  ements.** change
24510 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
24520 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  on of a database
24530 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65   connection, the
24540 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a  y do not make .*
24550 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  * changes to the
24560 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
24570 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
24580 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73  n disk..*/.int s
24590 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
245a0 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  only(sqlite3_stm
245b0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
245c0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
245d0 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61  rmine If A Prepa
245e0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61  red Statement Ha
245f0 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a  s Been Reset.**.
24600 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
24610 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74  stmt_busy(S) int
24620 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
24630 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
24640 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
24650 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
24660 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64  has been stepped
24670 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75   at least once u
24680 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
24690 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68  3_step(S)] but h
246a0 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f  as not run to co
246b0 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20  mpletion and/or 
246c0 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e  has not .** been
246d0 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71   reset using [sq
246e0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e  lite3_reset(S)].
246f0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
24700 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69  tmt_busy(S).** i
24710 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24720 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61   false if S is a
24730 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
24740 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a  If S is not a .*
24750 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  * NULL pointer a
24760 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e  nd is not a poin
24770 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b  ter to a valid [
24780 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24790 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74  nt].** object, t
247a0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
247b0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
247c0 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
247d0 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  irable..**.** Th
247e0 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
247f0 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62   be used in comb
24800 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33  ination [sqlite3
24810 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a  _next_stmt()].**
24820 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70   to locate all p
24830 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24840 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ts associated wi
24850 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a  th a database .*
24860 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  * connection tha
24870 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66  t are in need of
24880 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54   being reset.  T
24890 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c  his can be used,
248a0 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  .** for example,
248b0 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72   in diagnostic r
248c0 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63  outines to searc
248d0 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a  h for prepared .
248e0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  ** statements th
248f0 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61  at are holding a
24900 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65   transaction ope
24910 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
24920 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69  3_stmt_busy(sqli
24930 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
24940 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
24950 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
24960 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
24970 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
24980 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
24990 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
249a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
249b0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
249c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
249d0 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
249e0 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
249f0 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
24a00 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
24a10 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
24a20 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
24a30 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
24a40 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
24a50 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
24a60 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
24a70 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
24a80 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
24a90 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
24aa0 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
24ab0 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
24ac0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
24ad0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
24ae0 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
24af0 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
24b00 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
24b10 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
24b20 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
24b30 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
24b40 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
24b50 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
24b60 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
24b70 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
24b80 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
24b90 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
24ba0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
24bb0 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
24bc0 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
24bd0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
24be0 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
24bf0 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
24c00 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
24c10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
24c20 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
24c30 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
24c40 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
24c50 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
24c60 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20  ex is held.  An 
24c70 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
24c80 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
24c90 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
24ca0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
24cb0 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
24cc0 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
24cd0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
24ce0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
24cf0 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
24d00 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
24d10 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
24d20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
24d30 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
24d40 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
24d50 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
24d60 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
24d70 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
24d80 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
24d90 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
24da0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
24db0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
24dc0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
24dd0 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
24de0 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
24df0 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
24e00 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
24e10 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
24e20 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
24e30 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
24e40 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
24e50 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
24e60 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
24e70 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
24e80 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
24e90 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
24ea0 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
24eb0 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
24ec0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
24ed0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
24ee0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
24ef0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
24f00 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
24f10 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
24f20 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
24f30 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
24f40 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
24f50 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
24f60 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
24f70 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
24f80 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
24f90 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
24fa0 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
24fb0 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
24fc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
24fd0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
24fe0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
24ff0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
25000 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
25010 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
25020 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
25030 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
25040 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
25050 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
25060 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
25070 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
25080 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
25090 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
250a0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
250b0 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
250c0 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
250d0 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
250e0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
250f0 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
25100 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
25110 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
25120 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
25130 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
25140 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
25150 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
25160 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
25170 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
25180 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
25190 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
251a0 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
251b0 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
251c0 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
251d0 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
251e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
251f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
25200 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
25210 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
25220 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
25230 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
25240 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
25250 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
25260 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
25270 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
25280 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
25290 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
252a0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
252b0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
252c0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
252d0 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
252e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
252f0 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
25300 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
25310 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
25320 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
25330 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
25340 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
25350 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
25360 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
25370 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
25380 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
25390 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
253a0 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
253b0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
253c0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
253d0 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
253e0 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
253f0 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
25400 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
25410 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
25420 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a  r binding}.**.**
25430 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
25440 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
25450 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
25460 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
25470 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
25480 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
25490 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
254a0 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
254b0 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
254c0 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
254d0 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
254e0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
254f0 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
25500 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
25510 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
25520 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
25530 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
25540 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
25550 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
25560 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
25570 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
25580 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
25590 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
255a0 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  .)^  ^The values
255b0 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72   of these.** par
255c0 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
255d0 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
255e0 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22  eter names" or "
255f0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
25600 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
25610 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
25620 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
25630 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
25640 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
25650 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
25660 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
25670 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
25680 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
25690 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
256a0 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
256b0 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
256c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
256d0 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
256e0 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ariants..**.** ^
256f0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
25700 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
25710 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
25720 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
25730 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  .** ^The leftmos
25740 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
25750 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
25760 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61  1.  ^When the sa
25770 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
25780 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
25790 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
257a0 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
257b0 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
257c0 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
257d0 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
257e0 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
257f0 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65  ce..** ^The inde
25800 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
25810 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
25820 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
25830 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
25840 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
25850 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
25860 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65  ired.  ^The inde
25870 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
25880 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
25890 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
258a0 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75  ** ^The NNN valu
258b0 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
258c0 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
258d0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
258e0 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
258f0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
25900 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
25910 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
25920 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
25930 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
25940 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
25950 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
25960 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73  .**.** ^(In thos
25970 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  e routines that 
25980 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
25990 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
259a0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
259b0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
259c0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
259d0 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
259e0 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
259f0 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
25a00 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61  es</u> in the va
25a10 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
25a20 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
25a30 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.)^.** ^If the 
25a40 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
25a50 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
25a60 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
25a70 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65  string is.** the
25a80 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
25a90 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
25aa0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
25ab0 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65  ..** If a non-ne
25ac0 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61  gative fourth pa
25ad0 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69  rameter is provi
25ae0 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ded to sqlite3_b
25af0 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72  ind_text().** or
25b00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
25b10 78 74 31 36 28 29 20 74 68 65 6e 20 74 68 61 74  xt16() then that
25b20 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
25b30 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
25b40 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20  et.** where the 
25b50 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
25b60 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d  ould occur assum
25b70 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77  ing the string w
25b80 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69  ere NUL.** termi
25b90 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
25ba0 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
25bb0 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73  cur at byte offs
25bc0 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a  ets less than .*
25bd0 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * the value of t
25be0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
25bf0 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73  ter then the res
25c00 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61  ulting string va
25c10 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  lue will.** cont
25c20 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
25c30 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f  s.  The result o
25c40 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  f expressions in
25c50 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a  volving strings.
25c60 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  ** with embedded
25c70 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
25c80 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
25c90 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
25ca0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
25cb0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69  ob(), sqlite3_bi
25cc0 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a  nd_text(), and.*
25cd0 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  * sqlite3_bind_t
25ce0 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73  ext16() is a des
25cf0 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
25d00 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
25d10 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67  LOB or.** string
25d20 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
25d30 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
25d40 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75  it.  ^The destru
25d50 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a  ctor is called.*
25d60 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  * to dispose of 
25d70 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
25d80 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63  ng even if the c
25d90 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  all to sqlite3_b
25da0 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73  ind_blob(),.** s
25db0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
25dc0 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  (), or sqlite3_b
25dd0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61 69  ind_text16() fai
25de0 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65  ls.  .** ^If the
25df0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
25e00 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61  is.** the specia
25e10 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
25e20 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51  STATIC], then SQ
25e30 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
25e40 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  t the.** informa
25e50 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69  tion is in stati
25e60 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  c, unmanaged spa
25e70 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  ce and does not 
25e80 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64  need to be freed
25e90 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
25ea0 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  th argument has 
25eb0 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  the value [SQLIT
25ec0 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
25ed0 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  en.** SQLite mak
25ee0 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  es its own priva
25ef0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64  te copy of the d
25f00 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  ata immediately,
25f10 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73   before.** the s
25f20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
25f30 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e  routine returns.
25f40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
25f50 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
25f60 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
25f70 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
25f80 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
25f90 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
25fa0 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
25fb0 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
25fc0 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
25fd0 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
25fe0 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
25ff0 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
26000 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
26010 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
26020 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
26030 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
26040 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
26050 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
26060 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
26070 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
26080 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
26090 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
260a0 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
260b0 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
260c0 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
260d0 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
260e0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
260f0 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  OB..**.** ^If an
26100 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  y of the sqlite3
26110 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
26120 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69  es are called wi
26130 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
26140 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72  r.** for the [pr
26150 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26160 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70  ] or with a prep
26170 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66  ared statement f
26180 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  or which.** [sql
26190 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
261a0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72   been called mor
261b0 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20  e recently than 
261c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
261d0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  ],.** then the c
261e0 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  all will return 
261f0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
26200 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33    If any sqlite3
26210 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74  _bind_().** rout
26220 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20  ine is passed a 
26230 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26240 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65  ent] that has be
26250 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68  en finalized, th
26260 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75  e.** result is u
26270 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
26280 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  bably harmful..*
26290 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61  *.** ^Bindings a
262a0 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
262b0 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
262c0 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
262d0 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72  .** ^Unbound par
262e0 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
262f0 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
26300 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
26310 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69  te3_bind_* routi
26320 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
26330 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
26340 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  s or an.** [erro
26350 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68  r code] if anyth
26360 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
26370 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47  ** ^[SQLITE_RANG
26380 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  E] is returned i
26390 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a  f the parameter.
263a0 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  ** index is out 
263b0 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c  of range.  ^[SQL
263c0 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
263d0 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
263e0 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  () fails..**.** 
263f0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
26400 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
26410 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
26420 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
26430 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
26440 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
26450 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
26460 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
26470 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73  ite3_bind_blob(s
26480 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
26490 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
264a0 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
264b0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
264c0 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28  te3_bind_double(
264d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
264e0 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74  nt, double);.int
264f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
26500 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
26510 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20   int, int);.int 
26520 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
26530 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
26540 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69  , int, sqlite3_i
26550 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74  nt64);.int sqlit
26560 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
26570 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
26580 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
26590 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  nd_text(sqlite3_
265a0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
265b0 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20  t char*, int n, 
265c0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
265d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
265e0 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  d_text16(sqlite3
265f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
26600 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
26610 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
26620 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
26630 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
26640 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
26650 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
26660 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
26670 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  nd_zeroblob(sqli
26680 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
26690 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
266a0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
266b0 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72  Of SQL Parameter
266c0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
266d0 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
266e0 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
266f0 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72  mber of [SQL par
26700 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61  ameters].** in a
26710 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26720 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61  ment].  SQL para
26730 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e  meters are token
26740 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
26750 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a   "?", "?NNN", ":
26760 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72  AAA", "$AAA", or
26770 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72   "@AAA" that ser
26780 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f  ve as.** placeho
26790 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
267a0 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
267b0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
267c0 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
267d0 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
267e0 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
267f0 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
26800 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
26810 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
26820 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
26830 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
26840 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
26850 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
26860 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
26870 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
26880 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
26890 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
268a0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
268b0 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20  e ?NNN form are 
268c0 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
268d0 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
268e0 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e list.)^.**.** 
268f0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
26900 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
26910 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
26920 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
26930 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
26940 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
26950 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
26960 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
26970 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
26980 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
26990 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
269a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
269b0 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
269c0 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e  arameter.**.** ^
269d0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
269e0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
269f0 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  P,N) interface r
26a00 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61  eturns.** the na
26a10 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b  me of the N-th [
26a20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69  SQL parameter] i
26a30 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
26a40 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
26a50 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72   ^(SQL parameter
26a60 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
26a70 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
26a80 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
26a90 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d  A".** have a nam
26aa0 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73  e which is the s
26ab0 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20  tring "?NNN" or 
26ac0 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
26ad0 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65   or "$AAA".** re
26ae0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49  spectively..** I
26af0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
26b00 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f  he initial ":" o
26b10 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20  r "$" or "@" or 
26b20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64  "?".** is includ
26b30 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
26b40 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61  e name.)^.** ^Pa
26b50 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
26b60 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74  form "?" without
26b70 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74   a following int
26b80 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d  eger have no nam
26b90 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66  e.** and are ref
26ba0 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d  erred to as "nam
26bb0 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79  eless" or "anony
26bc0 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22  mous parameters"
26bd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
26be0 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
26bf0 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
26c00 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
26c10 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20  * ^If the value 
26c20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
26c30 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68  e or if the N-th
26c40 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
26c50 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20   nameless, then 
26c60 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
26c70 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
26c80 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
26c90 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e  ways in UTF-8 en
26ca0 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
26cb0 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
26cc0 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
26cd0 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
26ce0 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
26cf0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
26d00 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
26d10 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
26d20 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
26d30 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
26d40 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
26d50 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
26d60 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
26d70 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
26d80 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
26d90 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
26da0 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
26db0 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
26dc0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
26dd0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
26de0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
26df0 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
26e00 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
26e10 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a   Given Name.**.*
26e20 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e  * ^Return the in
26e30 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
26e40 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
26e50 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a  s name.  ^The.**
26e60 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
26e70 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
26e80 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
26e90 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
26ea0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
26eb0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
26ec0 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20  e3_bind()].  ^A 
26ed0 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72  zero.** is retur
26ee0 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69  ned if no matchi
26ef0 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ng parameter is 
26f00 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72  found.  ^The par
26f10 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d  ameter.** name m
26f20 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20  ust be given in 
26f30 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68  UTF-8 even if th
26f40 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
26f50 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70  ment.** was prep
26f60 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36  ared from UTF-16
26f70 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c   text using [sql
26f80 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
26f90 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
26fa0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
26fb0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
26fc0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
26fd0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
26fe0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
26ff0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
27000 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
27010 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
27020 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
27030 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
27040 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
27050 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
27060 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27070 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
27080 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
27090 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
270a0 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68   ^Contrary to th
270b0 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
270c0 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
270d0 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
270e0 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
270f0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
27100 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
27110 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27120 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74  ment]..** ^Use t
27130 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72  his routine to r
27140 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
27150 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
27160 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
27170 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
27180 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
27190 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
271a0 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
271b0 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
271c0 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  et.**.** ^Return
271d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
271e0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
271f0 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
27200 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
27210 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27220 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  . ^This routine 
27230 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74  returns 0 if pSt
27240 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20  mt is an SQL.** 
27250 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64  statement that d
27260 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64  oes not return d
27270 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ata (for example
27280 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a   an [UPDATE])..*
27290 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
272a0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
272b0 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
272c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
272d0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
272e0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
272f0 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
27300 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
27310 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  t Set.**.** ^The
27320 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
27330 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
27340 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
27350 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
27360 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
27370 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
27380 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20  tatement.  ^The 
27390 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
273a0 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
273b0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
273c0 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
273d0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
273e0 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
273f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
27400 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
27410 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
27420 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
27430 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
27440 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
27450 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65  eter is the [pre
27460 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27470 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  .** that impleme
27480 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  nts the [SELECT]
27490 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65   statement. ^The
274a0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
274b0 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r is the.** colu
274c0 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65  mn number.  ^The
274d0 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
274e0 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a   is number 0..**
274f0 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
27500 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  d string pointer
27510 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
27520 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70  either the [prep
27530 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
27540 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ** is destroyed 
27550 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  by [sqlite3_fina
27560 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
27570 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
27580 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
27590 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
275a0 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
275b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
275c0 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
275d0 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
275e0 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
275f0 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
27600 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f  _column_name() o
27610 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
27620 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65  _name16() on the
27630 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   same column..**
27640 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
27650 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64  malloc() fails d
27660 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73  uring the proces
27670 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72  sing of either r
27680 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65  outine.** (for e
27690 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20  xample during a 
276a0 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
276b0 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29  UTF-8 to UTF-16)
276c0 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20   then a.** NULL 
276d0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
276e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
276f0 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
27700 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
27710 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
27720 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
27730 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
27740 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
27750 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
27760 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
27770 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
27780 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
27790 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
277a0 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
277b0 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
277c0 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
277d0 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74  e next..*/.const
277e0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
277f0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
27800 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
27810 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
27820 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
27830 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
27840 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
27850 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
27860 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
27870 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
27880 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
27890 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
278a0 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
278b0 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61  the database, ta
278c0 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c  ble, and.** tabl
278d0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  e column that is
278e0 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61   the origin of a
278f0 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75   particular resu
27900 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20  lt column in.** 
27910 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
27920 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  nt..** ^The name
27930 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
27940 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
27950 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
27960 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
27970 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d   a UTF-8 or UTF-
27980 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
27990 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
279a0 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
279b0 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
279c0 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
279d0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
279e0 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
279f0 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
27a00 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
27a10 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
27a20 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
27a30 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
27a40 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
27a50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27a60 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
27a70 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
27a80 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
27a90 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
27aa0 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
27ab0 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
27ac0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
27ad0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
27ae0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
27af0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
27b00 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
27b10 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
27b20 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
27b30 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
27b40 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
27b50 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72  .** ^The names r
27b60 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
27b70 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
27b80 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
27b90 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
27ba0 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
27bb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
27bc0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
27bd0 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69  ese interfaces i
27be0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
27bf0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68  atement]..** ^Th
27c00 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
27c10 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
27c20 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72   about the Nth r
27c30 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74  esult column ret
27c40 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  urned by.** the 
27c50 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65  statement, where
27c60 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
27c70 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
27c80 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  nt..** ^The left
27c90 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  -most column is 
27ca0 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65  column 0 for the
27cb0 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
27cc0 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ** ^If the Nth c
27cd0 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
27ce0 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
27cf0 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
27d00 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
27d10 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
27d20 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
27d30 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
27d40 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
27d50 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72   NULL.  ^These r
27d60 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
27d70 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
27d80 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
27d90 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
27da0 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73  curs.  ^Otherwis
27db0 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
27dc0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
27dd0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
27de0 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63  , table,.** or c
27df0 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
27e00 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
27e10 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
27e20 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74  m..**.** ^As wit
27e30 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
27e40 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77  te APIs, those w
27e50 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77  hose names end w
27e60 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a  ith "16" return.
27e70 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  ** UTF-16 encode
27e80 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68  d strings and th
27e90 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
27ea0 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a  s return UTF-8..
27eb0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49  **.** ^These API
27ec0 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
27ed0 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
27ee0 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
27ef0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
27f00 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
27f10 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
27f20 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
27f30 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ol..**.** If two
27f40 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
27f50 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
27f60 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
27f70 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
27f80 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
27f90 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
27fa0 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
27fb0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
27fc0 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
27fd0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
27fe0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
27ff0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
28000 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69  or more.** [sqli
28010 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
28020 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d  ase_name | colum
28030 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
28040 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68  faces].** for th
28050 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  e same [prepared
28060 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
28070 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
28080 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
28090 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
280a0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
280b0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
280c0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
280d0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
280e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
280f0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
28100 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
28110 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
28120 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
28130 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
28140 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
28150 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
28160 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
28170 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
28180 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
28190 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
281a0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
281b0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
281c0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
281d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
281e0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
281f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
28200 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
28210 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
28220 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28230 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
28240 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
28250 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ult.**.** ^(The 
28260 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
28270 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
28280 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
28290 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
282a0 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  is a [SELECT] st
282b0 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
282c0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
282d0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65  e.** returned re
282e0 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74  sult set of that
282f0 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74   [SELECT] is a t
28300 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
28310 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
28320 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
28330 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
28340 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
28350 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
28360 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66  returned.)^  ^If
28370 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
28380 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
28390 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
283a0 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
283b0 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
283c0 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
283d0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  ed..** ^The retu
283e0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61  rned string is a
283f0 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f  lways UTF-8 enco
28400 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
28410 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20   example, given 
28420 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
28430 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
28440 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
28450 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e  RIANT);.**.** an
28460 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
28470 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
28480 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
28490 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
284a0 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
284b0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
284c0 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
284d0 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
284e0 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72  for the second r
284f0 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
28500 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
28510 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
28520 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
28530 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e  column (i==0).)^
28540 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
28550 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
28560 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53  time typing.  ^S
28570 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61  o just because a
28580 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65   column.** is de
28590 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69  clared to contai
285a0 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74  n a particular t
285b0 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61  ype does not mea
285c0 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61  n that the.** da
285d0 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61  ta stored in tha
285e0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74  t column is of t
285f0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
28600 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  .  SQLite is.** 
28610 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20  strongly typed, 
28620 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69  but the typing i
28630 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74  s dynamic not st
28640 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20  atic.  ^Type.** 
28650 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
28660 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
28670 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
28680 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
28690 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
286a0 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63  ose values..*/.c
286b0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
286c0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
286d0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
286e0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
286f0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
28700 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
28710 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
28720 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28730 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51  : Evaluate An SQ
28740 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  L Statement.**.*
28750 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
28760 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
28770 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
28780 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a   using either.**
28790 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
287a0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
287b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
287c0 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
287d0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
287e0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
287f0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
28800 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
28810 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
28820 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
28830 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
28840 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
28850 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
28860 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
28870 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
28880 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
28890 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
288a0 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
288b0 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
288c0 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
288d0 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
288e0 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
288f0 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
28900 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
28910 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
28920 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
28930 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
28940 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
28950 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
28960 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
28970 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
28980 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
28990 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
289a0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
289b0 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
289c0 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
289d0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
289e0 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
289f0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
28a00 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67  *.** ^In the leg
28a10 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
28a20 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
28a30 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b  will be either [
28a40 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a  SQLITE_BUSY],.**
28a50 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
28a60 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
28a70 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
28a80 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
28a90 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22  ..** ^With the "
28aa0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
28ab0 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
28ac0 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
28ad0 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
28ae0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
28af0 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
28b00 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  s well..**.** ^[
28b10 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61  SQLITE_BUSY] mea
28b20 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  ns that the data
28b30 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20  base engine was 
28b40 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72  unable to acquir
28b50 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  e the.** databas
28b60 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73  e locks it needs
28b70 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20   to do its job. 
28b80 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65   ^If the stateme
28b90 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
28ba0 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
28bb0 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
28bc0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
28bd0 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
28be0 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
28bf0 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
28c00 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
28c10 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
28c20 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a  ccurs within an.
28c30 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
28c40 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
28c50 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
28c60 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
28c70 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
28c80 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53  nuing..**.** ^[S
28c90 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
28ca0 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
28cb0 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
28cc0 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
28cd0 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
28ce0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
28cf0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
28d00 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
28d10 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
28d20 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
28d30 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
28d40 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
28d50 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
28d60 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
28d70 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
28d80 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tate..**.** ^If 
28d90 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
28da0 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
28db0 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
28dc0 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  a, then [SQLITE_
28dd0 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ROW].** is retur
28de0 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
28df0 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
28e00 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f  is ready for pro
28e10 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a  cessing by the.*
28e20 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  * caller. The va
28e30 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
28e40 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ssed using the [
28e50 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
28e60 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
28e70 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
28e80 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
28e90 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
28ea0 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
28eb0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52  .** ^[SQLITE_ERR
28ec0 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
28ed0 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
28ee0 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
28ef0 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
28f00 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
28f10 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
28f20 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
28f30 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
28f40 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
28f50 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
28f60 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
28f70 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
28f80 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68  msg()]..** ^With
28f90 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
28fa0 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
28fb0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
28fc0 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
28fd0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
28fe0 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
28ff0 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
29000 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
29010 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
29020 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
29030 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
29040 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
29050 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
29060 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65  ement].  ^In the
29070 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
29080 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
29090 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
290a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
290b0 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
290c0 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
290d0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
290e0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
290f0 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
29100 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
29110 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
29120 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
29130 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
29140 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
29150 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
29160 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
29170 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
29180 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
29190 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73   had.** previous
291a0 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  ly returned [SQL
291b0 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53  ITE_ERROR] or [S
291c0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72  QLITE_DONE].  Or
291d0 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20   it could.** be 
291e0 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
291f0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
29200 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65  connection is be
29210 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20  ing used by two 
29220 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61  or.** more threa
29230 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d  ds at the same m
29240 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a  oment in time..*
29250 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72  *.** For all ver
29260 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
29270 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64  up to and includ
29280 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20  ing 3.6.23.1, a 
29290 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
292a0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73  te3_reset()] was
292b0 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20   required after 
292c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72  sqlite3_step() r
292d0 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67  eturned anything
292e0 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  .** other than [
292f0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f  SQLITE_ROW] befo
29300 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  re any subsequen
29310 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a  t invocation of.
29320 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
29330 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72  ).  Failure to r
29340 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
29350 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
29360 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  g .** [sqlite3_r
29370 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65  eset()] would re
29380 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49  sult in an [SQLI
29390 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72  TE_MISUSE] retur
293a0 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  n from.** sqlite
293b0 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61  3_step().  But a
293c0 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36  fter version 3.6
293d0 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73  .23.1, sqlite3_s
293e0 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63  tep() began.** c
293f0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
29400 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74  reset()] automat
29410 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63  ically in this c
29420 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68  ircumstance rath
29430 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72  er.** than retur
29440 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ning [SQLITE_MIS
29450 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e  USE].  This is n
29460 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20  ot considered a 
29470 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a  compatibility.**
29480 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61   break because a
29490 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ny application t
294a0 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65  hat ever receive
294b0 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  s an SQLITE_MISU
294c0 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62  SE error.** is b
294d0 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74  roken by definit
294e0 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ion.  The [SQLIT
294f0 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54  E_OMIT_AUTORESET
29500 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
29510 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20  ption.** can be 
29520 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20  used to restore 
29530 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
29540 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ior..**.** <b>Go
29550 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
29560 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
29570 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
29580 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
29590 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
295a0 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
295b0 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
295c0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
295d0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
295e0 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
295f0 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
29600 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
29610 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
29620 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
29630 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
29640 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
29650 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
29660 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
29670 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
29680 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
29690 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
296a0 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
296b0 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
296c0 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
296d0 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
296e0 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
296f0 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
29700 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
29710 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
29720 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
29730 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
29740 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
29750 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
29760 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
29770 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
29780 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
29790 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
297a0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
297b0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
297c0 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
297d0 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
297e0 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
297f0 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
29800 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
29810 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
29820 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
29830 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
29840 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f   recommended..*/
29850 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65  .int sqlite3_ste
29860 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
29870 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29880 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  F: Number of col
29890 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74  umns in a result
298a0 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20   set.**.** ^The 
298b0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
298c0 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  nt(P) interface 
298d0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
298e0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
298f0 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
29900 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
29910 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72  t set of [prepar
29920 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
29930 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64  .** ^If prepared
29940 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65   statement P doe
29950 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c  s not have resul
29960 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75  ts ready to retu
29970 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73  rn.** (via calls
29980 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
29990 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71  _column_int | sq
299a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29  lite3_column_*()
299b0 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  ] of.** interfac
299c0 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  es) then sqlite3
299d0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
299e0 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68  eturns 0..** ^Th
299f0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
29a00 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
29a10 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69  also returns 0 i
29a20 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f P is a NULL po
29a30 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73  inter..** ^The s
29a40 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
29a50 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74  t(P) routine ret
29a60 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72  urns 0 if the pr
29a70 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a  evious call to.*
29a80 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  * [sqlite3_step]
29a90 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51  (P) returned [SQ
29aa0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68  LITE_DONE].  ^Th
29ab0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
29ac0 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20  ount(P).** will 
29ad0 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20  return non-zero 
29ae0 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  if previous call
29af0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
29b00 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a  p](P) returned.*
29b10 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  * [SQLITE_ROW], 
29b20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61  except in the ca
29b30 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d  se of the [PRAGM
29b40 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61  A incremental_va
29b50 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69  cuum].** where i
29b60 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
29b70 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68   zero since each
29b80 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75   step of that mu
29b90 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67  lti-step.** prag
29ba0 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c  ma returns 0 col
29bb0 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a  umns of data..**
29bc0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
29bd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
29be0 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71  unt()].*/.int sq
29bf0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
29c00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
29c10 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
29c20 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
29c30 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a  tal Datatypes.**
29c40 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
29c50 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45  E_TEXT.**.** ^(E
29c60 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
29c70 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
29c80 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
29c90 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
29ca0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
29cb0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
29cc0 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
29cd0 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
29ce0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
29cf0 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
29d00 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
29d10 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
29d20 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  )^.**.** These c
29d30 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
29d40 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
29d50 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
29d60 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
29d70 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
29d80 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
29d90 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
29da0 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
29db0 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
29dc0 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
29dd0 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
29de0 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
29df0 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
29e00 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
29e10 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
29e20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
29e30 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  , not.** SQLITE_
29e40 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
29e50 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
29e60 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
29e70 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
29e80 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
29e90 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
29ea0 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
29eb0 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
29ec0 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
29ed0 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
29ee0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
29ef0 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
29f00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
29f10 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
29f20 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
29f30 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  lt Values From A
29f40 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52   Query.** KEYWOR
29f50 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65  DS: {column acce
29f60 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  ss functions}.**
29f70 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
29f80 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73  es form the "res
29f90 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61  ult set" interfa
29fa0 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ce..**.** ^These
29fb0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
29fc0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
29fd0 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
29fe0 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
29ff0 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
2a000 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e  of a query.  ^In
2a010 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20   every case the 
2a020 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
2a030 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
2a040 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
2a050 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
2a060 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74  is being evaluat
2a070 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
2a080 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20  _stmt*].** that 
2a090 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
2a0a0 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
2a0b0 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
2a0c0 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
2a0d0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f  .** and the seco
2a0e0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
2a0f0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2a100 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
2a110 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
2a120 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
2a130 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  ed. ^The leftmos
2a140 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
2a150 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74  result set has t
2a160 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e  he index 0..** ^
2a170 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  The number of co
2a180 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
2a190 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  ult can be deter
2a1a0 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  mined using.** [
2a1b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2a1c0 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ount()]..**.** I
2a1d0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
2a1e0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
2a1f0 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
2a200 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
2a210 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
2a220 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
2a230 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
2a240 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
2a250 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2a260 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
2a270 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
2a280 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2a290 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
2a2a0 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
2a2b0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
2a2c0 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
2a2d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2a2e0 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
2a2f0 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
2a300 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
2a310 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
2a320 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
2a330 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
2a340 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
2a350 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
2a360 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2a370 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
2a380 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2a390 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
2a3a0 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
2a3b0 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
2a3c0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2a3d0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
2a3e0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
2a3f0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
2a400 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
2a410 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
2a420 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
2a430 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
2a440 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
2a450 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2a460 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
2a470 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
2a480 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2a490 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2a4a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2a4b0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
2a4c0 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
2a4d0 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
2a4e0 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
2a4f0 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
2a500 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
2a510 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e  esult column.  ^
2a520 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
2a530 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
2a540 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
2a550 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
2a560 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
2a570 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
2a580 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
2a590 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
2a5a0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2a5b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2a5c0 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
2a5d0 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
2a5e0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
2a5f0 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
2a600 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
2a610 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
2a620 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
2a630 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
2a640 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2a650 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
2a660 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
2a670 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
2a680 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
2a690 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
2a6a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a6b0 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
2a6c0 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
2a6d0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rsion..**.** ^If
2a6e0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2a6f0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73   BLOB or UTF-8 s
2a700 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
2a710 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2a720 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  tes().** routine
2a730 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2a740 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2a750 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
2a760 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2a770 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
2a780 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  16 string, then 
2a790 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2a7a0 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a  ytes() converts.
2a7b0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
2a7c0 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20   UTF-8 and then 
2a7d0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2a7e0 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
2a7f0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2a800 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
2a810 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
2a820 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
2a830 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
2a840 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
2a850 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
2a860 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
2a870 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
2a880 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2a890 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
2a8a0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2a8b0 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
2a8c0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2a8d0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74  lumn_bytes() ret
2a8e0 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
2a8f0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2a900 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
2a910 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20  -16 string then 
2a920 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
2a930 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20  mn_bytes16().** 
2a940 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2a950 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2a960 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
2a970 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
2a980 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2a990 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c   a UTF-8 string,
2a9a0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2a9b0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63  lumn_bytes16() c
2a9c0 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
2a9d0 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20  tring to UTF-16 
2a9e0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
2a9f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2aa00 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
2aa10 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
2aa20 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
2aa30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2aa40 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a  ytes16() uses.**
2aa50 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2aa60 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
2aa70 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
2aa80 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61   UTF-16 string a
2aa90 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
2aaa0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2aab0 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
2aac0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2aad0 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
2aae0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2aaf0 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72  _bytes16() retur
2ab00 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
2ab10 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
2ab20 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
2ab30 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
2ab40 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2ab50 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2ab60 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64  )] do not includ
2ab70 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
2ab80 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e  nators at the en
2ab90 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
2aba0 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74  ng.  ^For clarit
2abb0 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65  y: the values re
2abc0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
2abd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2abe0 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  es()] and [sqlit
2abf0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2ac00 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d  6()] are the num
2ac10 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
2ac20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
2ac30 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
2ac40 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
2ac50 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75  ** ^Strings retu
2ac60 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2ac70 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
2ac80 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2ac90 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
2aca0 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
2acb0 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
2acc0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
2acd0 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
2ace0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
2acf0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
2ad00 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
2ad10 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20   BLOB is a NULL 
2ad20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
2ad30 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
2ad40 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
2ad50 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
2ad60 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
2ad70 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2ad80 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e  lue] object.  An
2ad90 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
2ada0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2adb0 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  t.** may only be
2adc0 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69   used with [sqli
2add0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
2ade0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
2adf0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a  esult_value()]..
2ae00 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f  ** If the [unpro
2ae10 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2ae20 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74  alue] object ret
2ae30 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2ae40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2ae50 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20  e()] is used in 
2ae60 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69  any other way, i
2ae70 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a  ncluding calls.*
2ae80 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  * to routines li
2ae90 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ke [sqlite3_valu
2aea0 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74  e_int()], [sqlit
2aeb0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
2aec0 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
2aed0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
2aee0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2aef0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
2af00 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2af10 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f  tines attempt to
2af20 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
2af30 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72  ue where appropr
2af40 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65  iate.  ^For.** e
2af50 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
2af60 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
2af70 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
2af80 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
2af90 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
2afa0 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
2afb0 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
2afc0 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65  internally to pe
2afd0 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e  rform the.** con
2afe0 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69  version automati
2aff0 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f  cally.  ^(The fo
2b000 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
2b010 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
2b020 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72  sions.** that ar
2b030 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
2b040 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
2b050 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
2b060 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
2b070 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
2b080 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
2b090 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
2b0a0 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
2b0b0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2b0c0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2b0d0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
2b0e0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2b0f0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
2b100 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
2b110 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
2b120 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2b130 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2b140 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
2b150 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
2b160 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2b170 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2b180 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
2b190 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
2b1a0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2b1b0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2b1c0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
2b1d0 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
2b1e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2b1f0 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
2b200 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
2b210 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
2b220 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
2b230 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2b240 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2b250 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
2b260 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
2b270 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
2b280 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
2b290 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61  onvert from floa
2b2a0 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20  t to integer.** 
2b2b0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2b2c0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2b2d0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
2b2e0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
2b2f0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
2b300 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
2b310 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
2b320 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a   as FLOAT->TEXT.
2b330 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
2b340 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  T    <td> INTEGE
2b350 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f  R   <td> Use ato
2b360 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
2b370 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46   TEXT    <td>  F
2b380 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65  LOAT    <td> Use
2b390 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
2b3a0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
2b3b0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2b3c0 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74   No change.** <t
2b3d0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
2b3e0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2b3f0 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
2b400 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
2b410 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
2b420 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46   BLOB    <td>  F
2b430 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
2b440 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
2b450 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  n use atof().** 
2b460 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
2b470 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2b480 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f   <td> Add a zero
2b490 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e   terminator if n
2b4a0 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eeded.** </table
2b4b0 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  >.** </blockquot
2b4c0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  e>)^.**.** The t
2b4d0 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73  able above makes
2b4e0 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74   reference to st
2b4f0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
2b500 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28   functions atoi(
2b510 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e  ).** and atof().
2b520 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f    SQLite does no
2b530 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65  t really use the
2b540 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49  se functions.  I
2b550 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e  t has its.** own
2b560 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65   equivalent inte
2b570 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20  rnal routines.  
2b580 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61  The atoi() and a
2b590 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a  tof() names are.
2b5a0 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74  ** used in the t
2b5b0 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79  able for brevity
2b5c0 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65   and because the
2b5d0 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74  y are familiar t
2b5e0 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67  o most.** C prog
2b5f0 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e  rammers..**.** N
2b600 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
2b610 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
2b620 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
2b630 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
2b640 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
2b650 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2b660 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
2b670 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
2b680 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2b690 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
2b6a0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
2b6b0 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
2b6c0 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
2b6d0 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
2b6e0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
2b6f0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
2b700 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
2b710 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
2b720 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
2b730 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
2b740 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2b750 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2b760 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2b770 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
2b780 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
2b790 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
2b7a0 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
2b7b0 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
2b7c0 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
2b7d0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2b7e0 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
2b7f0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2b800 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
2b810 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2b820 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
2b830 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
2b840 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
2b850 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
2b860 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
2b870 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
2b880 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
2b890 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
2b8a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2b8b0 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
2b8c0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2b8d0 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
2b8e0 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
2b8f0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
2b900 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
2b910 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
2b920 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73  >.**.** ^Convers
2b930 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46  ions between UTF
2b940 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36  -16be and UTF-16
2b950 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f  le are always do
2b960 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20  ne in place and 
2b970 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69  do.** not invali
2b980 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69  date a prior poi
2b990 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20  nter, though of 
2b9a0 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65  course the conte
2b9b0 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  nt of the buffer
2b9c0 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69  .** that the pri
2b9d0 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72  or pointer refer
2b9e0 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20  ences will have 
2b9f0 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20  been modified.  
2ba00 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f  Other kinds.** o
2ba10 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65  f conversion are
2ba20 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77   done in place w
2ba30 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62  hen it is possib
2ba40 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65  le, but sometime
2ba50 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f  s they.** are no
2ba60 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69  t possible and i
2ba70 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72  n those cases pr
2ba80 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65  ior pointers are
2ba90 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
2baa0 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61  .** The safest a
2bab0 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65  nd easiest to re
2bac0 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73  member policy is
2bad0 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
2bae0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
2baf0 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
2bb00 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
2bb10 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71   <ul>.**  <li>sq
2bb20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2bb30 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  t() followed by 
2bb40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2bb50 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
2bb60 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
2bb70 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77  mn_blob() follow
2bb80 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2bb90 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
2bba0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
2bbb0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2bbc0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
2bbd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2bbe0 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c  es16()</li>.** <
2bbf0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74  /ul>.**.** In ot
2bc00 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73  her words, you s
2bc10 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74  hould call sqlit
2bc20 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2bc30 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ,.** sqlite3_col
2bc40 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73  umn_blob(), or s
2bc50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2bc60 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20  xt16() first to 
2bc70 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74  force the result
2bc80 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73  .** into the des
2bc90 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65  ired format, the
2bca0 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  n invoke sqlite3
2bcb0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2bcc0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
2bcd0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74  lumn_bytes16() t
2bce0 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20  o find the size 
2bcf0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20  of the result.  
2bd00 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  Do not mix calls
2bd10 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
2bd20 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20  olumn_text() or 
2bd30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2bd40 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73  lob() with calls
2bd50 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
2bd60 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c  olumn_bytes16(),
2bd70 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20   and do not mix 
2bd80 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2bd90 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2bda0 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74  .** with calls t
2bdb0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2bdc0 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20  _bytes()..**.** 
2bdd0 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65  ^The pointers re
2bde0 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64  turned are valid
2bdf0 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f   until a type co
2be00 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20  nversion occurs 
2be10 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20  as.** described 
2be20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20  above, or until 
2be30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2be40 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
2be50 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
2be60 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2be70 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68   is called.  ^Th
2be80 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
2be90 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
2bea0 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73  ngs.** and BLOBs
2beb0 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
2bec0 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e  tically.  Do <b>
2bed0 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65  not</b> pass the
2bee0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
2bef0 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ed.** [sqlite3_c
2bf00 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
2bf10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2bf20 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
2bf30 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  o.** [sqlite3_fr
2bf40 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ee()]..**.** ^(I
2bf50 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2bf60 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
2bf70 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76  rs during the ev
2bf80 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a  aluation of any.
2bf90 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ** of these rout
2bfa0 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20  ines, a default 
2bfb0 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
2bfc0 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
2bfd0 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68  value.** is eith
2bfe0 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30  er the integer 0
2bff0 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  , the floating p
2c000 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c  oint number 0.0,
2c010 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   or a NULL.** po
2c020 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65  inter.  Subseque
2c030 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
2c040 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
2c050 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  will return.** [
2c060 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e  SQLITE_NOMEM].)^
2c070 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
2c080 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c090 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2c0a0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2c0b0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2c0c0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73  _bytes(sqlite3_s
2c0d0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2c0e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2c0f0 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
2c100 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2c110 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  Col);.double sql
2c120 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
2c130 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
2c140 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
2c150 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c160 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
2c170 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
2c180 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
2c190 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
2c1a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2c1b0 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
2c1c0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
2c1d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2c1e0 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
2c1f0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
2c200 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2c210 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2c220 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2c230 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2c240 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2c250 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2c260 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
2c270 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74  te3_value *sqlit
2c280 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2c290 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2c2a0 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  nt iCol);../*.**
2c2b0 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72   CAPI3REF: Destr
2c2c0 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74  oy A Prepared St
2c2d0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
2c2e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2c2f0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e  3_finalize() fun
2c300 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
2c310 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65  to delete a [pre
2c320 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c330 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  ..** ^If the mos
2c340 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
2c350 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
2c360 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64  ment encountered
2c370 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72   no errors.** or
2c380 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
2c390 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20  t is never been 
2c3a0 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20  evaluated, then 
2c3b0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2c3c0 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  () returns.** SQ
2c3d0 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68  LITE_OK.  ^If th
2c3e0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
2c3f0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74  aluation of stat
2c400 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20  ement S failed, 
2c410 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
2c420 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75  finalize(S) retu
2c430 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69  rns the appropri
2c440 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
2c450 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
2c460 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a   error code]..**
2c470 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2c480 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75  _finalize(S) rou
2c490 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
2c4a0 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
2c4b0 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69  during.** the li
2c4c0 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65  fe cycle of [pre
2c4d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c4e0 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74   S:.** before st
2c4f0 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65  atement S is eve
2c500 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74  r evaluated, aft
2c510 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
2c520 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  e calls to [sqli
2c530 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72  te3_reset()], or
2c540 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a   after any call.
2c550 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ** to [sqlite3_s
2c560 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73  tep()] regardles
2c570 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
2c580 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  not the statemen
2c590 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  t has.** complet
2c5a0 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a  ed execution..**
2c5b0 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71  .** ^Invoking sq
2c5c0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2c5d0 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   on a NULL point
2c5e0 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  er is a harmless
2c5f0 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68   no-op..**.** Th
2c600 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
2c610 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72  st finalize ever
2c620 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  y [prepared stat
2c630 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20  ement] in order 
2c640 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f  to avoid.** reso
2c650 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20  urce leaks.  It 
2c660 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72  is a grievous er
2c670 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  ror for the appl
2c680 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74  ication to try t
2c690 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61  o use.** a prepa
2c6a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66  red statement af
2c6b0 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
2c6c0 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20  finalized.  Any 
2c6d0 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  use of a prepare
2c6e0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  d.** statement a
2c6f0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
2c700 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72   finalized can r
2c710 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
2c720 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69  ed and.** undesi
2c730 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73  rable behavior s
2c740 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73  uch as segfaults
2c750 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70   and heap corrup
2c760 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
2c770 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
2c780 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2c790 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2c7a0 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
2c7b0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2c7c0 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
2c7d0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
2c7e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
2c7f0 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
2c800 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c810 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
2c820 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
2c830 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
2c840 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
2c850 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74  ..** ^Any SQL st
2c860 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
2c870 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
2c880 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
2c890 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
2c8a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2c8b0 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
2c8c0 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
2c8d0 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
2c8e0 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
2c8f0 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
2c900 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
2c910 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ings..**.** ^The
2c920 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2c930 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
2c940 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
2c950 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
2c960 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62  ** back to the b
2c970 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
2c980 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  program..**.** ^
2c990 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2c9a0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2c9b0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
2c9c0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2c9d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
2c9e0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2c9f0 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
2ca00 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20  DONE],.** or if 
2ca10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2ca20 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
2ca30 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
2ca40 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  n S,.** then [sq
2ca50 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2ca60 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
2ca70 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  OK]..**.** ^If t
2ca80 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2ca90 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2caa0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
2cab0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2cac0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
2cad0 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
2cae0 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hen.** [sqlite3_
2caf0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
2cb00 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
2cb10 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
2cb20 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
2cb30 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
2cb40 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
2cb50 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
2cb60 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c  s.** of any [sql
2cb70 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
2cb80 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
2cb90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2cba0 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] S..*/.int s
2cbb0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
2cbc0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2cbd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2cbe0 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
2cbf0 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
2cc00 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
2cc10 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
2cc20 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
2cc30 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
2cc40 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2cc50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
2cc60 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
2cc70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2cc80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
2cc90 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
2cca0 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
2ccb0 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
2ccc0 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
2ccd0 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
2cce0 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
2ccf0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
2cd00 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
2cd10 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
2cd20 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
2cd30 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
2cd40 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
2cd50 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
2cd60 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e  ferences between
2cd70 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
2cd80 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20  es are the text 
2cd90 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65  encoding expecte
2cda0 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63  d for.** the sec
2cdb0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74  ond parameter (t
2cdc0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66  he name of the f
2cdd0 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72  unction being cr
2cde0 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68  eated).** and th
2cdf0 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62  e presence or ab
2ce00 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72  sence of a destr
2ce10 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66  uctor callback f
2ce20 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  or.** the applic
2ce30 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
2ce40 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  er..**.** ^The f
2ce50 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
2ce60 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
2ce70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
2ce80 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
2ce90 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
2cea0 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e  e added.  ^If an
2ceb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65   application use
2cec0 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
2ced0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
2cee0 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c  ection then appl
2cef0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2cf00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
2cf10 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74  st be added.** t
2cf20 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
2cf30 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72  connection separ
2cf40 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ately..**.** ^Th
2cf50 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2cf60 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
2cf70 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
2cf80 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
2cf90 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
2cfa0 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
2cfb0 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
2cfc0 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
2cfd0 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a  es in a UTF-8.**
2cfe0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c   representation,
2cff0 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
2d000 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
2d010 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  r.  ^Note that t
2d020 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74  he name.** lengt
2d030 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54  h limit is in UT
2d040 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63  F-8 bytes, not c
2d050 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54  haracters nor UT
2d060 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a  F-16 bytes.  .**
2d070 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f   ^Any attempt to
2d080 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
2d090 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
2d0a0 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
2d0b0 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
2d0c0 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65  MISUSE] being re
2d0d0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
2d0e0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2d0f0 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
2d100 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
2d110 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
2d120 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2d130 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
2d140 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61  kes. ^If this pa
2d150 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74  rameter is -1, t
2d160 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
2d170 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2d180 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
2d190 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
2d1a0 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20  ments between 0 
2d1b0 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a  and the limit.**
2d1c0 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33   set by [sqlite3
2d1d0 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
2d1e0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
2d1f0 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68  RG]).  If the th
2d200 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
2d210 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31   is less than -1
2d220 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
2d230 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65   127 then the be
2d240 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
2d250 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2d260 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2d270 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
2d280 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
2d290 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
2d2a0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
2d2b0 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
2d2c0 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
2d2d0 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
2d2e0 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74   Every SQL funct
2d2f0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
2d300 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20  on must be able 
2d310 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20  to work.** with 
2d320 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c  UTF-8, UTF-16le,
2d330 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42   or UTF-16be.  B
2d340 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e  ut some implemen
2d350 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a  tations may be.*
2d360 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74  * more efficient
2d370 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69   with one encodi
2d380 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e  ng than another.
2d390 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f    ^An applicatio
2d3a0 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20  n may.** invoke 
2d3b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2d3c0 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  unction() or sql
2d3d0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2d3e0 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c  tion16() multipl
2d3f0 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20  e.** times with 
2d400 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2d410 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  n but with diffe
2d420 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65  rent values of e
2d430 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65  TextRep..** ^Whe
2d440 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
2d450 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
2d460 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2d470 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
2d480 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
2d490 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
2d4a0 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
2d4b0 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
2d4c0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
2d4d0 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c   If there is onl
2d4e0 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65  y a single imple
2d4f0 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20  mentation which 
2d500 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68  does not care wh
2d510 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64  at text.** encod
2d520 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
2d530 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
2d540 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
2d550 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a  [SQLITE_ANY]..**
2d560 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20  .** ^(The fifth 
2d570 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
2d580 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
2d590 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
2d5a0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
2d5b0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
2d5c0 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
2d5d0 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
2d5e0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
2d5f0 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ta()].)^.**.** ^
2d600 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e  The sixth, seven
2d610 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61  th and eighth pa
2d620 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
2d630 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
2d640 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
2d650 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
2d660 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
2d670 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
2d680 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2d690 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73   aggregate. ^A s
2d6a0 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
2d6b0 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
2d6c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2d6d0 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
2d6e0 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c  llback only; NUL
2d6f0 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20  L pointers must 
2d700 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
2d710 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
2d720 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
2d730 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53   ^An aggregate S
2d740 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
2d750 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
2d760 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
2d770 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
2d780 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d  d NULL pointer m
2d790 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f  ust be passed fo
2d7a0 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
2d7b0 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
2d7c0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
2d7d0 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
2d7e0 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  ss NULL pointers
2d7f0 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
2d800 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
2d810 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  acks..**.** ^(If
2d820 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d   the ninth param
2d830 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2d840 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
2d850 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  v2() is not NULL
2d860 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
2d870 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
2d880 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2d890 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a  ata pointer. .**
2d8a0 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
2d8b0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
2d8c0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
2d8d0 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20  deleted, either 
2d8e0 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72  by being.** over
2d8f0 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74  loaded or when t
2d900 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2d910 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e  ection closes.)^
2d920 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63  .** ^The destruc
2d930 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f  tor is also invo
2d940 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ked if the call 
2d950 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  to.** sqlite3_cr
2d960 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
2d970 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68  () fails..** ^Wh
2d980 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  en the destructo
2d990 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  r callback of th
2d9a0 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65  e tenth paramete
2d9b0 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  r is invoked, it
2d9c0 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20  .** is passed a 
2d9d0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
2d9e0 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20  which is a copy 
2d9f0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2da00 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e  on data .** poin
2da10 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68  ter which was th
2da20 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
2da30 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
2da40 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
2da50 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  )..**.** ^It is 
2da60 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
2da70 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
2da80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2da90 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
2daa0 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
2dab0 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
2dac0 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
2dad0 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
2dae0 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
2daf0 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
2db00 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
2db10 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
2db20 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
2db30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
2db40 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
2db50 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
2db60 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
2db70 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
2db80 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  ed.  ^A function
2db90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2dba0 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
2dbb0 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
2dbc0 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
2dbd0 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
2dbe0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2dbf0 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
2dc00 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
2dc10 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
2dc20 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
2dc30 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
2dc40 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
2dc50 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
2dc60 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
2dc70 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
2dc80 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
2dc90 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
2dca0 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75  rent.  .** ^A fu
2dcb0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
2dcc0 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
2dcd0 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
2dce0 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
2dcf0 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
2dd00 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
2dd10 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
2dd20 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
2dd30 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
2dd40 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
2dd50 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c  F16..**.** ^Buil
2dd60 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
2dd70 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
2dd80 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
2dd90 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2dda0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  tions..**.** ^An
2ddb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2ddc0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
2ddd0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
2dde0 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
2ddf0 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
2de00 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
2de10 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
2de20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
2de30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
2de40 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
2de50 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
2de60 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
2de70 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
2de80 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2de90 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2dea0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
2deb0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
2dec0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
2ded0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
2dee0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
2def0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
2df00 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
2df10 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
2df20 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2df30 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2df40 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
2df50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2df60 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2df70 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
2df80 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
2df90 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
2dfa0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2dfb0 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
2dfc0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
2dfd0 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  void *zFunctionN
2dfe0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
2dff0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2e000 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
2e010 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
2e020 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2e030 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2e040 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2e050 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
2e060 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2e070 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2e080 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
2e090 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
2e0a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2e0b0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
2e0c0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
2e0d0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
2e0e0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
2e0f0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
2e100 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
2e110 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
2e120 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
2e130 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2e140 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2e150 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
2e160 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2e170 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2e180 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2e190 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
2e1a0 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69  context*),.  voi
2e1b0 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
2e1c0 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
2e1d0 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63  PI3REF: Text Enc
2e1e0 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65  odings.**.** The
2e1f0 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  se constant defi
2e200 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
2e210 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20   that represent 
2e220 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74  the various.** t
2e230 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75  ext encodings su
2e240 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
2e250 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
2e260 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20  LITE_UTF8       
2e270 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
2e280 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
2e290 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2e2a0 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20  LITE_UTF16BE    
2e2b0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
2e2c0 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
2e2d0 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
2e2e0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2e2f0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
2e300 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
2e310 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74     5    /* sqlit
2e320 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2e330 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  on only */.#defi
2e340 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  ne SQLITE_UTF16_
2e350 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a  ALIGNED  8    /*
2e360 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2e370 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a  collation only *
2e380 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
2e390 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
2e3a0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
2e3b0 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
2e3c0 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
2e3d0 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
2e3e0 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
2e3f0 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
2e400 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
2e410 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
2e420 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
2e430 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
2e440 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
2e450 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
2e460 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
2e470 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
2e480 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
2e490 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e  ons.  To help en
2e4a0 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74  courage people t
2e4b0 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67  o avoid.** using
2e4c0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2e4d0 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69  , we are not goi
2e4e0 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77  ng to tell you w
2e4f0 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  hat they do..*/.
2e500 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
2e510 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53  MIT_DEPRECATED.S
2e520 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2e530 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67   int sqlite3_agg
2e540 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
2e550 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2e560 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2e570 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
2e580 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
2e590 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
2e5a0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2e5b0 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
2e5c0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
2e5d0 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
2e5e0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
2e5f0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2e600 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
2e610 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
2e620 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
2e630 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
2e640 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51  leanup(void);.SQ
2e650 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2e660 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
2e670 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
2e680 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
2e690 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c  nt64,int),void*,
2e6a0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
2e6b0 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
2e6c0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
2e6d0 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50  g SQL Function P
2e6e0 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a  arameter Values.
2e6f0 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
2e700 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
2e710 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
2e720 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
2e730 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
2e740 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
2e750 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
2e760 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
2e770 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
2e780 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
2e790 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
2e7a0 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
2e7b0 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
2e7c0 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
2e7d0 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
2e7e0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
2e7f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2e800 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
2e810 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2e820 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
2e830 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
2e840 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
2e850 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
2e860 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
2e870 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d  ** The 3rd param
2e880 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
2e890 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
2e8a0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
2e8b0 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
2e8c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2e8d0 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
2e8e0 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
2e8f0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
2e900 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
2e910 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
2e920 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
2e930 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
2e940 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
2e950 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
2e960 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2e970 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
2e980 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
2e990 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
2e9a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e9b0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
2e9c0 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
2e9d0 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
2e9e0 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
2e9f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2ea00 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
2ea10 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
2ea20 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
2ea30 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2ea40 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
2ea50 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
2ea60 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61  onding [column a
2ea70 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
2ea80 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
2ea90 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2eaa0 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70  take a single [p
2eab0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2eac0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a  _value] object.*
2ead0 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  * pointer instea
2eae0 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  d of a [sqlite3_
2eaf0 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61  stmt*] pointer a
2eb00 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  nd an integer co
2eb10 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  lumn number..**.
2eb20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2eb30 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69  value_text16() i
2eb40 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74  nterface extract
2eb50 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
2eb60 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69  g.** in the nati
2eb70 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66  ve byte-order of
2eb80 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e   the host machin
2eb90 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
2eba0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2ebb0 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
2ebc0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
2ebd0 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
2ebe0 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73  extract UTF-16 s
2ebf0 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
2ec00 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
2ec10 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
2ec20 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ely..**.** ^(The
2ec30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
2ec40 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
2ec50 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
2ec60 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
2ec70 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
2ec80 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
2ec90 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
2eca0 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
2ecb0 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
2ecc0 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
2ecd0 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
2ece0 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
2ecf0 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
2ed00 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
2ed10 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
2ed20 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74  formation (in ot
2ed30 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66  her.** words, if
2ed40 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
2ed50 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
2ed60 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
2ed70 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
2ed80 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f  version is perfo
2ed90 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rmed.  Otherwise
2eda0 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
2edb0 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53  ccurs..** The [S
2edc0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
2edd0 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20  datatype] after 
2ede0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65  conversion is re
2edf0 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  turned.)^.**.** 
2ee00 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69  Please pay parti
2ee10 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20  cular attention 
2ee20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74  to the fact that
2ee30 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74   the pointer ret
2ee40 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
2ee50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
2ee60 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  b()], [sqlite3_v
2ee70 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72  alue_text()], or
2ee80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
2ee90 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e  ue_text16()] can
2eea0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20   be invalidated 
2eeb0 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20  by a subsequent 
2eec0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2eed0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2eee0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2eef0 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b  ue_bytes16()], [
2ef00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2ef10 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
2ef20 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2ef30 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  16()]..**.** The
2ef40 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
2ef50 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2ef60 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2ef70 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  as.** the SQL fu
2ef80 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70  nction that supp
2ef90 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65  lied the [sqlite
2efa0 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65  3_value*] parame
2efb0 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  ters..*/.const v
2efc0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2efd0 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
2efe0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2eff0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2f000 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2f010 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
2f020 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
2f030 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75  te3_value*);.dou
2f040 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
2f050 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
2f060 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2f070 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
2f080 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2f090 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
2f0a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2f0b0 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
2f0c0 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  *);.const unsign
2f0d0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
2f0e0 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
2f0f0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
2f100 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2f110 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
2f120 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
2f130 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2f140 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
2f150 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2f160 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2f170 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2f180 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
2f190 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2f1a0 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
2f1b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2f1c0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2f1d0 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
2f1e0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
2f1f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2f200 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
2f210 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
2f220 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e  t.**.** Implemen
2f230 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65  tations of aggre
2f240 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
2f250 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72  ns use this.** r
2f260 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
2f270 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74  te memory for st
2f280 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
2f290 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
2f2a0 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
2f2b0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2f2c0 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
2f2d0 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a  ine is called .*
2f2e0 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  * for a particul
2f2f0 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  ar aggregate fun
2f300 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a  ction, SQLite.**
2f310 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20   allocates N of 
2f320 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f  memory, zeroes o
2f330 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20  ut that memory, 
2f340 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
2f350 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
2f360 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20  new memory. ^On 
2f370 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
2f380 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
2f390 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
2f3a0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f  ate_context() fo
2f3b0 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  r the same aggre
2f3c0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
2f3d0 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73  stance,.** the s
2f3e0 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65  ame buffer is re
2f3f0 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33  turned.  Sqlite3
2f400 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2f410 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79  xt() is normally
2f420 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20  .** called once 
2f430 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74  for each invocat
2f440 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70  ion of the xStep
2f450 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68   callback and th
2f460 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74  en one.** last t
2f470 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69  ime when the xFi
2f480 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  nal callback is 
2f490 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e  invoked.  ^(When
2f4a0 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a   no rows match.*
2f4b0 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71  * an aggregate q
2f4c0 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28  uery, the xStep(
2f4d0 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  ) callback of th
2f4e0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
2f4f0 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  tion.** implemen
2f500 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20  tation is never 
2f510 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61  called and xFina
2f520 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78  l() is called ex
2f530 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49  actly once..** I
2f540 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73  n those cases, s
2f550 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2f560 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74  _context() might
2f570 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   be called for t
2f580 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65  he.** first time
2f590 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69   from within xFi
2f5a0 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  nal().)^.**.** ^
2f5b0 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  The sqlite3_aggr
2f5c0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
2f5d0 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  N) routine retur
2f5e0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
2f5f0 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73  r if N is.** les
2f600 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
2f610 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20  to zero or if a 
2f620 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20  memory allocate 
2f630 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
2f640 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74  .** ^(The amount
2f650 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61   of space alloca
2f660 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61  ted by sqlite3_a
2f670 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2f680 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65  (C,N) is.** dete
2f690 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20  rmined by the N 
2f6a0 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72  parameter on fir
2f6b0 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  st successful ca
2f6c0 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68  ll.  Changing th
2f6d0 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20  e.** value of N 
2f6e0 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
2f6f0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ll to sqlite3_ag
2f700 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2f710 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  ) within.** the 
2f720 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
2f730 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
2f740 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65   will not resize
2f750 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
2f760 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a  llocation.)^.**.
2f770 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
2f780 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
2f790 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
2f7a0 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
2f7b0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2f7c0 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
2f7d0 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
2f7e0 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
2f7f0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
2f800 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
2f810 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
2f820 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
2f830 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
2f840 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
2f850 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2f860 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
2f870 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
2f880 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
2f890 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
2f8a0 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
2f8b0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
2f8c0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
2f8d0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2f8e0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2f8f0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
2f900 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
2f910 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
2f920 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
2f930 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2f940 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  ntext(sqlite3_co
2f950 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74  ntext*, int nByt
2f960 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  es);../*.** CAPI
2f970 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20  3REF: User Data 
2f980 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
2f990 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2f9a0 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
2f9b0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2f9c0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
2f9d0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
2f9e0 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
2f9f0 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
2fa00 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
2fa10 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2fa20 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2fa30 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
2fa40 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2fa50 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
2fa60 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
2fa70 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
2fa80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2fa90 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
2faa0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2fab0 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
2fac0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2fad0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2fae0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
2faf0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2fb00 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
2fb10 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2fb20 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
2fb30 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
2fb40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2fb50 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2fb60 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ion For Function
2fb70 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
2fb80 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
2fb90 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61  handle() interfa
2fba0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
2fbb0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
2fbc0 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ter to the [data
2fbd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2fbe0 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65   (the 1st parame
2fbf0 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
2fc00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2fc10 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
2fc20 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2fc30 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
2fc40 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
2fc50 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
2fc60 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
2fc70 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
2fc80 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69  unction..*/.sqli
2fc90 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e  te3 *sqlite3_con
2fca0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73  text_db_handle(s
2fcb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2fcc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2fcd0 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69  F: Function Auxi
2fce0 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a  liary Data.**.**
2fcf0 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
2fd00 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  wo functions may
2fd10 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c   be used by scal
2fd20 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ar SQL functions
2fd30 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   to.** associate
2fd40 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61   metadata with a
2fd50 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20  rgument values. 
2fd60 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  If the same valu
2fd70 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a  e is passed to.*
2fd80 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63  * multiple invoc
2fd90 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2fda0 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
2fdb0 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65  during query exe
2fdc0 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a  cution, under.**
2fdd0 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e   some circumstan
2fde0 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74  ces the associat
2fdf0 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20  ed metadata may 
2fe00 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68  be preserved. Th
2fe10 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65  is may.** be use
2fe20 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  d, for example, 
2fe30 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72  to add a regular
2fe40 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
2fe50 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66  hing scalar.** f
2fe60 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d  unction. The com
2fe70 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  piled version of
2fe80 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
2fe90 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65  ression is store
2fea0 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61  d as.** metadata
2feb0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2fec0 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70   the SQL value p
2fed0 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67  assed as the reg
2fee0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a  ular expression.
2fef0 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65  ** pattern.  The
2ff00 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
2ff10 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
2ff20 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
2ff30 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
2ff40 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2ff50 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68  e function so th
2ff60 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  at the original 
2ff70 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a  pattern string.*
2ff80 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  * does not need 
2ff90 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64  to be recompiled
2ffa0 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74   on each invocat
2ffb0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
2ffc0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2ffd0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
2ffe0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2fff0 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74  r to the metadat
30000 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
30010 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  by the sqlite3_s
30020 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e  et_auxdata() fun
30030 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e  ction with the N
30040 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76  th argument.** v
30050 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c  alue to the appl
30060 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
30070 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f  function. ^If no
30080 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65   metadata has be
30090 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20  en ever.** been 
300a0 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20  set for the Nth 
300b0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
300c0 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20  function, or if 
300d0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
300e0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61  g.** function pa
300f0 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e  rameter has chan
30100 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65  ged since the me
30110 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c  ta-data was set,
30120 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
30130 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72  _get_auxdata() r
30140 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
30150 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
30160 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
30170 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
30180 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61  e saves the meta
30190 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  data.** pointed 
301a0 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61  to by its 3rd pa
301b0 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d  rameter as the m
301c0 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20  etadata for the 
301d0 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  N-th.** argument
301e0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
301f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
30200 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e  tion.  Subsequen
30210 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  t.** calls to sq
30220 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
30230 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e  a() might return
30240 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69   this data, if i
30250 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65  t has.** not bee
30260 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20  n destroyed..** 
30270 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55  ^If it is not NU
30280 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  LL, SQLite will 
30290 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
302a0 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  uctor.** functio
302b0 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34  n given by the 4
302c0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
302d0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
302e0 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20  ata() on.** the 
302f0 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68  metadata when th
30300 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
30310 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
30320 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72  er changes.** or
30330 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   when the SQL st
30340 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65  atement complete
30350 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  s, whichever com
30360 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20  es first..**.** 
30370 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
30380 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72  o call the destr
30390 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d  uctor and drop m
303a0 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a  etadata on any.*
303b0 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61  * parameter of a
303c0 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61  ny function at a
303d0 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f  ny time.  ^The o
303e0 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73  nly guarantee is
303f0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73   that.** the des
30400 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20  tructor will be 
30410 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68  called before th
30420 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72  e metadata is dr
30430 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  opped..**.** ^(I
30440 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61  n practice, meta
30450 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
30460 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
30470 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
30480 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74  expressions that
30490 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74   are constant at
304a0 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54   compile time. T
304b0 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74  his includes lit
304c0 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61  eral.** values a
304d0 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e  nd [parameters].
304e0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )^.**.** These r
304f0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
30500 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
30510 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
30520 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
30530 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
30540 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
30550 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
30560 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
30570 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64  t*, int N);.void
30580 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
30590 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
305a0 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f  text*, int N, vo
305b0 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f  id*, void (*)(vo
305c0 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  id*));.../*.** C
305d0 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e  API3REF: Constan
305e0 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63  ts Defining Spec
305f0 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42  ial Destructor B
30600 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68  ehavior.**.** Th
30610 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20  ese are special 
30620 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64  values for the d
30630 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
30640 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
30650 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
30660 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
30670 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
30680 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
30690 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74  ^If the destruct
306a0 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
306b0 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
306c0 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
306d0 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
306e0 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
306f0 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
30700 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
30710 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
30720 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68   destroyed.  ^Th
30730 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e  e.** SQLITE_TRAN
30740 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e  SIENT value mean
30750 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
30760 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63  nt will likely c
30770 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20  hange in.** the 
30780 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20  near future and 
30790 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75  that SQLite shou
307a0 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20  ld make its own 
307b0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a  private copy of.
307c0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62  ** the content b
307d0 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
307e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64  .**.** The typed
307f0 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20  ef is necessary 
30800 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70  to work around p
30810 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61  roblems in certa
30820 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c  in.** C++ compil
30830 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74  ers.  See ticket
30840 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64   #2191..*/.typed
30850 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
30860 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
30870 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
30880 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
30890 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
308a0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
308b0 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
308c0 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
308d0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
308e0 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
308f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
30900 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
30910 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
30920 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  on.**.** These r
30930 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
30940 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
30950 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
30960 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
30970 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
30980 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
30990 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
309a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
309b0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
309c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
309d0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
309e0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
309f0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
30a00 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
30a10 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
30a20 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20   the [parameter 
30a30 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20  binding] family 
30a40 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  of.** functions 
30a50 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c  used to bind val
30a60 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
30a70 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
30a80 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
30a90 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b  * Refer to the [
30aa0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64  SQL parameter] d
30ab0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
30ac0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
30ad0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  rmation..**.** ^
30ae0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
30af0 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
30b00 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
30b10 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
30b20 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
30b30 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
30b40 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
30b50 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
30b60 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
30b70 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
30b80 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
30b90 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
30ba0 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
30bb0 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
30bc0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
30bd0 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
30be0 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73  b() interfaces s
30bf0 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  et the result of
30c00 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
30c10 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
30c20 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f  tion to be a BLO
30c30 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c  B containing all
30c40 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61   zero.** bytes a
30c50 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  nd N bytes in si
30c60 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  ze, where N is t
30c70 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
30c80 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  2nd parameter..*
30c90 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
30ca0 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
30cb0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
30cc0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
30cd0 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
30ce0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
30cf0 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61  ion to be a floa
30d00 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
30d10 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
30d20 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
30d30 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
30d40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30d50 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
30d60 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
30d70 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63  ) functions.** c
30d80 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ause the impleme
30d90 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  nted SQL functio
30da0 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  n to throw an ex
30db0 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c  ception..** ^SQL
30dc0 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
30dd0 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
30de0 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
30df0 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
30e00 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
30e10 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
30e20 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
30e30 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
30e40 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
30e50 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70    ^SQLite interp
30e60 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  rets the error.*
30e70 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  * message string
30e80 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
30e90 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20  sult_error() as 
30ea0 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a  UTF-8. ^SQLite.*
30eb0 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  * interprets the
30ec0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
30ed0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
30ee0 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20  r16() as UTF-16 
30ef0 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74  in native.** byt
30f00 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68  e order.  ^If th
30f10 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
30f20 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
30f30 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
30f40 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
30f50 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65  _error16() is ne
30f60 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
30f70 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20  te takes as the 
30f80 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
30f90 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72   all text up thr
30fa0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
30fb0 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
30fc0 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
30fd0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
30fe0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
30ff0 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  r() or.** sqlite
31000 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
31010 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  () is non-negati
31020 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
31030 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a  akes that many.*
31040 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  * bytes (not cha
31050 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68  racters) from th
31060 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
31070 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  as the error mes
31080 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  sage..** ^The sq
31090 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
310a0 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
310b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
310c0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61  ).** routines ma
310d0 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70  ke a private cop
310e0 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d  y of the error m
310f0 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f  essage text befo
31100 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72  re.** they retur
31110 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  n.  Hence, the c
31120 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
31130 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f  can deallocate o
31140 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20  r.** modify the 
31150 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20  text after they 
31160 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68  return without h
31170 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  arm..** ^The sql
31180 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31190 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f  r_code() functio
311a0 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72  n changes the er
311b0 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75  ror code.** retu
311c0 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  rned by SQLite a
311d0 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e  s a result of an
311e0 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63   error in a func
311f0 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75  tion.  ^By defau
31200 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  lt,.** the error
31210 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f   code is SQLITE_
31220 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65  ERROR.  ^A subse
31230 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
31240 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
31250 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
31260 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
31270 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
31280 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
31290 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
312a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
312b0 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e  sult_toobig() in
312c0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
312d0 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
312e0 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63  n error.** indic
312f0 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72  ating that a str
31300 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74  ing or BLOB is t
31310 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  oo long to repre
31320 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sent..**.** ^The
31330 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31340 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63  nomem() interfac
31350 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
31360 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f  to throw an erro
31370 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20  r.** indicating 
31380 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c  that a memory al
31390 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e  location failed.
313a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
313b0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
313c0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
313d0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
313e0 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
313f0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
31400 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
31410 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
31420 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
31430 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
31440 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  d argument..** ^
31450 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
31460 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72  lt_int64() inter
31470 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
31480 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
31490 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
314a0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
314b0 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62  n to be the 64-b
314c0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
314d0 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
314e0 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
314f0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
31500 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31510 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  null() interface
31520 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
31530 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
31540 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
31550 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
31560 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
31570 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
31580 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  ult_text(), sqli
31590 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
315a0 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  6(),.** sqlite3_
315b0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
315c0 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
315d0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29  esult_text16be()
315e0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73   interfaces.** s
315f0 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  et the return va
31600 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  lue of the appli
31610 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
31620 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  unction to be.**
31630 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77   a text string w
31640 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e  hich is represen
31650 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54  ted as UTF-8, UT
31660 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
31670 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31   order,.** UTF-1
31680 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c  6 little endian,
31690 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65   or UTF-16 big e
316a0 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
316b0 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ely..** ^SQLite 
316c0 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72  takes the text r
316d0 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61  esult from the a
316e0 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a  pplication from.
316f0 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  ** the 2nd param
31700 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69  eter of the sqli
31710 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
31720 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
31730 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61  ^If the 3rd para
31740 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
31750 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
31760 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
31770 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
31780 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72  n SQLite takes r
31790 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20  esult text from 
317a0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
317b0 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65  r.** through the
317c0 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
317d0 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
317e0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
317f0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
31800 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
31810 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e  rfaces.** is non
31820 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
31830 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e  as many bytes (n
31840 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f  ot characters) o
31850 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f  f the text.** po
31860 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
31870 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72  2nd parameter ar
31880 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61  e taken as the a
31890 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
318a0 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  ed.** function r
318b0 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33  esult.  If the 3
318c0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
318d0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
318e0 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65  en it.** must be
318f0 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74   the byte offset
31900 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67   into the string
31910 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74   where the NUL t
31920 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a  erminator would.
31930 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74 68 65  ** appear if the
31940 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55   string where NU
31950 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  L terminated.  I
31960 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
31970 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ters occur.** in
31980 20 74 68 65 20 73 74 72 69 6e 67 20 61 74 20 61   the string at a
31990 20 62 79 74 65 20 6f 66 66 73 65 74 20 74 68 61   byte offset tha
319a0 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74  t is less than t
319b0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
319c0 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  3rd.** parameter
319d0 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
319e0 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c  ting string will
319f0 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65   contain embedde
31a00 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a  d NULs and the.*
31a10 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72  * result of expr
31a20 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e  essions operatin
31a30 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74  g on strings wit
31a40 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  h embedded NULs 
31a50 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
31a60 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
31a70 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
31a80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
31a90 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
31aa0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
31ab0 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e  lt_blob is a non
31ac0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
31ad0 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73  hen SQLite calls
31ae0 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f   that.** functio
31af0 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63  n as the destruc
31b00 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20  tor on the text 
31b10 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77  or BLOB result w
31b20 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69  hen it has.** fi
31b30 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
31b40 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
31b50 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
31b60 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
31b70 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
31b80 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a  nterfaces or to.
31b90 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
31ba0 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
31bb0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
31bc0 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68  QLITE_STATIC, th
31bd0 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73  en SQLite.** ass
31be0 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65  umes that the te
31bf0 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
31c00 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74  t is in constant
31c10 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
31c20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20  not.** copy the 
31c30 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70  content of the p
31c40 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c  arameter nor cal
31c50 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f  l a destructor o
31c60 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a  n the content.**
31c70 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
31c80 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
31c90 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
31ca0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
31cb0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
31cc0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
31cd0 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
31ce0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
31cf0 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
31d00 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
31d10 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74  E_TRANSIENT.** t
31d20 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  hen SQLite makes
31d30 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72   a copy of the r
31d40 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65  esult into space
31d50 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a   obtained from.*
31d60 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
31d70 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65  malloc()] before
31d80 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
31d90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31da0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
31db0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
31dc0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
31dd0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
31de0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
31df0 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65  to be a copy the
31e00 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
31e10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
31e20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64  object specified
31e30 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
31e40 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20  meter.  ^The.** 
31e50 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
31e60 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
31e70 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
31e80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
31e90 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20  lue].** so that 
31ea0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
31eb0 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e  ue] specified in
31ec0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d   the parameter m
31ed0 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  ay change or.** 
31ee0 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61  be deallocated a
31ef0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73  fter sqlite3_res
31f00 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75  ult_value() retu
31f10 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d  rns without harm
31f20 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74  ..** ^A [protect
31f30 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
31f40 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77  ] object may alw
31f50 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72  ays be used wher
31f60 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  e an.** [unprote
31f70 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
31f80 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65  ue] object is re
31f90 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65  quired, so eithe
31fa0 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71  r.** kind of [sq
31fb0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
31fc0 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  ect can be used 
31fd0 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66  with this interf
31fe0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ace..**.** If th
31ff0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
32000 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74   called from wit
32010 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e  hin the differen
32020 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e  t thread.** than
32030 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e   the one contain
32040 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74  ing the applicat
32050 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
32060 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76  tion that receiv
32070 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ed.** the [sqlit
32080 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e  e3_context] poin
32090 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73  ter, the results
320a0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
320b0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
320c0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69  result_blob(sqli
320d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
320e0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
320f0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
32100 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
32110 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69  sult_double(sqli
32120 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f  te3_context*, do
32130 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69  uble);.void sqli
32140 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
32150 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32160 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
32170 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
32180 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
32190 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
321a0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
321b0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
321c0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
321d0 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f  _toobig(sqlite3_
321e0 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
321f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32200 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74  rror_nomem(sqlit
32210 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
32220 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
32230 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c  t_error_code(sql
32240 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
32250 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
32260 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c  3_result_int(sql
32270 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
32280 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
32290 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73  3_result_int64(s
322a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
322b0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
322c0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
322d0 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  sult_null(sqlite
322e0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
322f0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
32300 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  _text(sqlite3_co
32310 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
32320 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  ar*, int, void(*
32330 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
32340 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
32350 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ext16(sqlite3_co
32360 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
32370 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
32380 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
32390 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
323a0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
323b0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
323c0 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
323d0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
323e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
323f0 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
32400 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
32410 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
32420 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
32430 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
32440 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63  _value(sqlite3_c
32450 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
32460 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73  _value*);.void s
32470 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
32480 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  roblob(sqlite3_c
32490 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b  ontext*, int n);
324a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
324b0 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c  : Define New Col
324c0 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73  lating Sequences
324d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
324e0 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d  nctions add, rem
324f0 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61  ove, or modify a
32500 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73   [collation] ass
32510 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20  ociated.** with 
32520 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
32530 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
32540 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  ied as the first
32550 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
32560 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
32570 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61  e collation is a
32580 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
32590 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
325a0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
325b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61  and sqlite3_crea
325c0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
325d0 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31  ).** and a UTF-1
325e0 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
325f0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f  ve byte order fo
32600 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
32610 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a  _collation16()..
32620 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61  ** ^Collation na
32630 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65  mes that compare
32640 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67   equal according
32650 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72   to [sqlite3_str
32660 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20  nicmp()] are.** 
32670 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65  considered to be
32680 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a   the same name..
32690 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72  **.** ^(The thir
326a0 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78  d argument (eTex
326b0 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e  tRep) must be on
326c0 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e  e of the constan
326d0 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  ts:.** <ul>.** <
326e0 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  li> [SQLITE_UTF8
326f0 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
32700 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20  TE_UTF16LE],.** 
32710 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
32720 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  16BE],.** <li> [
32730 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f  SQLITE_UTF16], o
32740 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  r.** <li> [SQLIT
32750 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
32760 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  ..** </ul>)^.** 
32770 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72  ^The eTextRep ar
32780 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65  gument determine
32790 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f  s the encoding o
327a0 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64  f strings passed
327b0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  .** to the colla
327c0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
327d0 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63  llback, xCallbac
327e0 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  k..** ^The [SQLI
327f0 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53  TE_UTF16] and [S
32800 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
32810 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20  NED] values for 
32820 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63  eTextRep.** forc
32830 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20  e strings to be 
32840 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76  UTF16 with nativ
32850 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
32860 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54   ^The [SQLITE_UT
32870 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c  F16_ALIGNED] val
32880 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20  ue for eTextRep 
32890 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74  forces strings t
328a0 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e  o begin.** on an
328b0 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65   even byte addre
328c0 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ss..**.** ^The f
328d0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
328e0 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c  pArg, is an appl
328f0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
32900 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73  nter that is pas
32910 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  sed.** through a
32920 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
32930 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c  ment to the coll
32940 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
32950 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
32960 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
32970 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69  nt, xCallback, i
32980 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
32990 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
329a0 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69  ction..** ^Multi
329b0 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ple collating fu
329c0 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72  nctions can be r
329d0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
329e0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
329f0 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72  t.** with differ
32a00 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72  ent eTextRep par
32a10 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69  ameters and SQLi
32a20 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63  te will use whic
32a30 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  hever.** functio
32a40 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c  n requires the l
32a50 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
32a60 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69  ata transformati
32a70 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78  on..** ^If the x
32a80 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e  Callback argumen
32a90 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  t is NULL then t
32aa0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
32ab0 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65  ction is.** dele
32ac0 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20  ted.  ^When all 
32ad0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
32ae0 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73  ons having the s
32af0 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c  ame name are del
32b00 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f  eted,.** that co
32b10 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f  llation is no lo
32b20 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a  nger usable..**.
32b30 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e  ** ^The collatin
32b40 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
32b50 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
32b60 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ith a copy of th
32b70 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69  e pArg .** appli
32b80 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
32b90 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f  ter and with two
32ba0 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20   strings in the 
32bb0 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69  encoding specifi
32bc0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65  ed.** by the eTe
32bd0 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20  xtRep argument. 
32be0 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   The collating f
32bf0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74  unction must ret
32c00 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65  urn an.** intege
32c10 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69  r that is negati
32c20 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73  ve, zero, or pos
32c30 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20  itive.** if the 
32c40 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20  first string is 
32c50 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c  less than, equal
32c60 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20   to, or greater 
32c70 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c  than the second,
32c80 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
32c90 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66  .  A collating f
32ca0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77  unction must alw
32cb0 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73  ays return the s
32cc0 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69  ame answer.** gi
32cd0 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70  ven the same inp
32ce0 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20  uts.  If two or 
32cf0 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66  more collating f
32d00 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67  unctions are reg
32d10 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68  istered.** to th
32d20 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e  e same collation
32d30 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66   name (using dif
32d40 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20  ferent eTextRep 
32d50 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c  values) then all
32d60 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e  .** must give an
32d70 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77   equivalent answ
32d80 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20  er when invoked 
32d90 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20  with equivalent 
32da0 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20  strings..** The 
32db0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
32dc0 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65  on must obey the
32dd0 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65   following prope
32de0 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a  rties for all.**
32df0 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61   strings A, B, a
32e00 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  nd C:.**.** <ol>
32e10 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42  .** <li> If A==B
32e20 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c   then B==A..** <
32e30 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20  li> If A==B and 
32e40 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a  B==C then A==C..
32e50 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b  ** <li> If A&lt;
32e60 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a  B THEN B&gt;A..*
32e70 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42  * <li> If A&lt;B
32e80 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e   and B&lt;C then
32e90 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c   A&lt;C..** </ol
32ea0 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c  >.**.** If a col
32eb0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
32ec0 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65  fails any of the
32ed0 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e   above constrain
32ee0 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63  ts and that.** c
32ef0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
32f00 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64  n is  registered
32f10 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20   and used, then 
32f20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
32f30 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64  SQLite.** is und
32f40 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
32f50 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
32f60 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
32f70 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
32f80 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
32f90 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74  tion().** with t
32fa0 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  he addition that
32fb0 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61   the xDestroy ca
32fc0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
32fd0 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a  d on pArg when.*
32fe0 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  * the collating 
32ff0 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65  function is dele
33000 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69  ted..** ^Collati
33010 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  ng functions are
33020 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68   deleted when th
33030 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65  ey are overridde
33040 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61  n by later.** ca
33050 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  lls to the colla
33060 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75  tion creation fu
33070 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20  nctions or when 
33080 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
33090 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
330a0 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71  closed using [sq
330b0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
330c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74  **.** ^The xDest
330d0 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  roy callback is 
330e0 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65  <u>not</u> calle
330f0 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c  d if the .** sql
33100 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
33110 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74  ation_v2() funct
33120 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c  ion fails.  Appl
33130 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e  ications that in
33140 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
33150 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33160 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e  _v2() with a non
33170 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61  -NULL xDestroy a
33180 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a  rgument should .
33190 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ** check the ret
331a0 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73  urn code and dis
331b0 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c  pose of the appl
331c0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
331d0 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76  nter.** themselv
331e0 65 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65  es rather than e
331f0 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20  xpecting SQLite 
33200 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20  to deal with it 
33210 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69  for them..** Thi
33220 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66  s is different f
33230 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20  rom every other 
33240 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
33250 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74  .  The inconsist
33260 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f  ency .** is unfo
33270 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e  rtunate but cann
33280 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69  ot be changed wi
33290 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62  thout breaking b
332a0 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d  ackwards .** com
332b0 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
332c0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71  * See also:  [sq
332d0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
332e0 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73  needed()] and [s
332f0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
33300 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f  _needed16()]..*/
33310 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
33320 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20  ate_collation(. 
33330 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
33340 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
33350 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
33360 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
33370 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
33380 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
33390 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
333a0 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  t void*).);.int 
333b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
333c0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73  ollation_v2(.  s
333d0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
333e0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
333f0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
33400 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
33410 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
33420 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
33430 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
33440 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  void*),.  void(*
33450 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
33460 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
33470 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33480 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
33490 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
334a0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78  Name,.  int eTex
334b0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
334c0 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
334d0 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
334e0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
334f0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
33500 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33510 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65   Collation Neede
33520 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  d Callbacks.**.*
33530 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69  * ^To avoid havi
33540 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61  ng to register a
33550 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ll collation seq
33560 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20  uences before a 
33570 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20  database.** can 
33580 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c  be used, a singl
33590 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
335a0 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73  ion may be regis
335b0 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a  tered with the.*
335c0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
335d0 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e  ection] to be in
335e0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
335f0 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  n undefined coll
33600 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
33610 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a  e is required..*
33620 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e  *.** ^If the fun
33630 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65  ction is registe
33640 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71  red using the sq
33650 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
33660 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a  needed() API,.**
33670 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73   then it is pass
33680 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  ed the names of 
33690 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
336a0 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73  ion sequences as
336b0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f   strings.** enco
336c0 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49  ded in UTF-8. ^I
336d0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  f sqlite3_collat
336e0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69  ion_needed16() i
336f0 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e  s used,.** the n
33700 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20  ames are passed 
33710 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63  as UTF-16 in mac
33720 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65  hine native byte
33730 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61   order..** ^A ca
33740 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e  ll to either fun
33750 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74  ction replaces t
33760 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c  he existing coll
33770 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c  ation-needed cal
33780 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57  lback..**.** ^(W
33790 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
337a0 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65   is invoked, the
337b0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
337c0 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79  passed is a copy
337d0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  .** of the secon
337e0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
337f0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
33800 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73  needed() or.** s
33810 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
33820 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68  _needed16().  Th
33830 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
33840 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73  t is the databas
33850 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
33860 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
33870 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
33880 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53  SQLITE_UTF8], [S
33890 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a  QLITE_UTF16BE],.
338a0 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ** or [SQLITE_UT
338b0 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69  F16LE], indicati
338c0 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69  ng the most desi
338d0 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68  rable form of th
338e0 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  e collation.** s
338f0 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e  equence function
33900 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20   required.  The 
33910 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
33920 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
33930 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20  the.** required 
33940 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
33950 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ce.)^.**.** The 
33960 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
33970 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65  n should registe
33980 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f  r the desired co
33990 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  llation using.**
339a0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
339b0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b  _collation()], [
339c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
339d0 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f  ollation16()], o
339e0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  r.** [sqlite3_cr
339f0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
33a00 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  2()]..*/.int sql
33a10 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
33a20 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33  eeded(.  sqlite3
33a30 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20  *, .  void*, .  
33a40 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
33a50 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
33a60 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  Rep,const char*)
33a70 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
33a80 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
33a90 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
33aa0 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64  .  void*,.  void
33ab0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
33ac0 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
33ad0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
33ae0 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48  .#ifdef SQLITE_H
33af0 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53  AS_CODEC./*.** S
33b00 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66  pecify the key f
33b10 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20  or an encrypted 
33b20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20  database.  This 
33b30 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62  routine should b
33b40 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68  e.** called righ
33b50 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  t after sqlite3_
33b60 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  open()..**.** Th
33b70 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
33b80 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
33b90 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
33ba0 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
33bb0 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
33bc0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
33bd0 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  _key(.  sqlite3 
33be0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
33bf0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
33c00 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
33c10 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
33c20 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
33c30 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20       /* The key 
33c40 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61  */.);../*.** Cha
33c50 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61  nge the key on a
33c60 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e  n open database.
33c70 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74    If the current
33c80 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74   database is not
33c90 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74  .** encrypted, t
33ca0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
33cb0 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66   encrypt it.  If
33cc0 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77   pNew==0 or nNew
33cd0 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61  ==0, the.** data
33ce0 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65  base is decrypte
33cf0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  d..**.** The cod
33d00 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
33d10 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
33d20 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
33d30 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
33d40 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
33d50 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65  int sqlite3_reke
33d60 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
33d70 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
33d80 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
33d90 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
33da0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
33db0 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
33dc0 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79    /* The new key
33dd0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70   */.);../*.** Sp
33de0 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61  ecify the activa
33df0 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53  tion key for a S
33e00 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e  EE database.  Un
33e10 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74  less .** activat
33e20 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  ed, none of the 
33e30 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  SEE routines wil
33e40 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20  l work..*/.void 
33e50 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
33e60 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68  _see(.  const ch
33e70 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20  ar *zPassPhrase 
33e80 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61         /* Activa
33e90 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29  tion phrase */.)
33ea0 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66  ;.#endif..#ifdef
33eb0 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43   SQLITE_ENABLE_C
33ec0 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  EROD./*.** Speci
33ed0 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f  fy the activatio
33ee0 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f  n key for a CERO
33ef0 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  D database.  Unl
33f00 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
33f10 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43  d, none of the C
33f20 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69  EROD routines wi
33f30 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64  ll work..*/.void
33f40 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74   sqlite3_activat
33f50 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74  e_cerod(.  const
33f60 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61   char *zPassPhra
33f70 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74  se        /* Act
33f80 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a  ivation phrase *
33f90 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  /.);.#endif../*.
33fa0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73  ** CAPI3REF: Sus
33fb0 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46  pend Execution F
33fc0 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a  or A Short Time.
33fd0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
33fe0 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69  3_sleep() functi
33ff0 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75  on causes the cu
34000 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20  rrent thread to 
34010 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f  suspend executio
34020 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73  n.** for at leas
34030 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  t a number of mi
34040 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69  lliseconds speci
34050 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61  fied in its para
34060 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  meter..**.** If 
34070 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
34080 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75  stem does not su
34090 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75  pport sleep requ
340a0 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c  ests with.** mil
340b0 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65  lisecond time re
340c0 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74  solution, then t
340d0 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20  he time will be 
340e0 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a  rounded up to.**
340f0 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63   the nearest sec
34100 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20  ond. The number 
34110 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
34120 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c  of sleep actuall
34130 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66  y.** requested f
34140 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e  rom the operatin
34150 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75  g system is retu
34160 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  rned..**.** ^SQL
34170 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  ite implements t
34180 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79  his interface by
34190 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c   calling the xSl
341a0 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  eep().** method 
341b0 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
341c0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
341d0 65 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c  ect.  If the xSl
341e0 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20  eep() method.** 
341f0 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  of the default V
34200 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d  FS is not implem
34210 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c  ented correctly,
34220 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   or not implemen
34230 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74  ted at.** all, t
34240 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
34250 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65   of sqlite3_slee
34260 70 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20  p() may deviate 
34270 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70  from the descrip
34280 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70  tion.** in the p
34290 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
342a0 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  hs..*/.int sqlit
342b0 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a  e3_sleep(int);..
342c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
342d0 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64  Name Of The Fold
342e0 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f  er Holding Tempo
342f0 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a  rary Files.**.**
34300 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61   ^(If this globa
34310 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61  l variable is ma
34320 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61  de to point to a
34330 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
34340 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
34350 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e  a folder (a.k.a.
34360 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65   directory), the
34370 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20  n all temporary 
34380 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  files.** created
34390 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20   by SQLite when 
343a0 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e  using a built-in
343b0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
343c0 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  VFS].** will be 
343d0 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64  placed in that d
343e0 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66  irectory.)^  ^If
343f0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
34400 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
34410 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
34420 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72   performs a sear
34430 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70  ch for an approp
34440 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61  riate.** tempora
34450 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72  ry file director
34460 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e  y..**.** It is n
34470 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
34480 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
34490 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20  ariable in more 
344a0 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65  than one.** thre
344b0 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49  ad at a time.  I
344c0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
344d0 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
344e0 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
344f0 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20   if a [database 
34500 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
34510 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65  eing used at the
34520 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20   same time in a 
34530 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65  separate.** thre
34540 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74  ad..** It is int
34550 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20  ended that this 
34560 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20  variable be set 
34570 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20  once.** as part 
34580 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  of process initi
34590 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65  alization and be
345a0 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20  fore any SQLite 
345b0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75  interface.** rou
345c0 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20  tines have been 
345d0 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20  called and that 
345e0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65  this variable re
345f0 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a  main unchanged.*
34600 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a  * thereafter..**
34610 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73  .** ^The [temp_s
34620 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
34630 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66  ragma] may modif
34640 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  y this variable 
34650 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20  and cause.** it 
34660 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f  to point to memo
34670 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
34680 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
34690 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65  ].  ^Furthermore
346a0 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73  ,.** the [temp_s
346b0 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
346c0 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73  ragma] always as
346d0 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73  sumes that any s
346e0 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68  tring.** that th
346f0 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e  is variable poin
34700 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e  ts to is held in
34710 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
34720 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
34730 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74  e3_malloc] and t
34740 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74  he pragma may at
34750 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68  tempt to free th
34760 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69  at memory.** usi
34770 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
34780 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20  ]..** Hence, if 
34790 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73  this variable is
347a0 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74   modified direct
347b0 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68  ly, either it sh
347c0 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20  ould be.** made 
347d0 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20  NULL or made to 
347e0 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
347f0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
34800 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a  qlite3_malloc].*
34810 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73  * or else the us
34820 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73  e of the [temp_s
34830 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
34840 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65  ragma] should be
34850 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c   avoided..*/.SQL
34860 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20  ITE_EXTERN char 
34870 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  *sqlite3_temp_di
34880 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20  rectory;../*.** 
34890 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46  CAPI3REF: Test F
348a0 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d  or Auto-Commit M
348b0 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ode.** KEYWORDS:
348c0 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   {autocommit mod
348d0 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e}.**.** ^The sq
348e0 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
348f0 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65  mmit() interface
34900 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
34910 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20  o or.** zero if 
34920 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61  the given databa
34930 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
34940 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75   or is not in au
34950 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a  tocommit mode,.*
34960 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
34970 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
34980 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75  e is on by defau
34990 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d  lt..** ^Autocomm
349a0 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62  it mode is disab
349b0 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d  led by a [BEGIN]
349c0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
349d0 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
349e0 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79  is re-enabled by
349f0 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b   a [COMMIT] or [
34a00 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a  ROLLBACK]..**.**
34a10 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64   If certain kind
34a20 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75  s of errors occu
34a30 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74  r on a statement
34a40 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d   within a multi-
34a50 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61  statement.** tra
34a60 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73  nsaction (errors
34a70 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49   including [SQLI
34a80 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54  TE_FULL], [SQLIT
34a90 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51  E_IOERR],.** [SQ
34aa0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51  LITE_NOMEM], [SQ
34ab0 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20  LITE_BUSY], and 
34ac0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
34ad0 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  T]) then the.** 
34ae0 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68  transaction migh
34af0 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t be rolled back
34b00 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
34b10 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f   The only way to
34b20 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65  .** find out whe
34b30 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f  ther SQLite auto
34b40 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
34b50 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61   back the transa
34b60 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61  ction after.** a
34b70 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73  n error is to us
34b80 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  e this function.
34b90 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65  .**.** If anothe
34ba0 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73  r thread changes
34bb0 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20   the autocommit 
34bc0 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61  status of the da
34bd0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
34be0 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20  tion while this 
34bf0 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69  routine is runni
34c00 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74  ng, then the ret
34c10 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  urn value.** is 
34c20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e  undefined..*/.in
34c30 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  t sqlite3_get_au
34c40 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33  tocommit(sqlite3
34c50 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
34c60 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61  REF: Find The Da
34c70 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66  tabase Handle Of
34c80 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
34c90 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ement.**.** ^The
34ca0 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
34cb0 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  le interface ret
34cc0 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61  urns the [databa
34cd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
34ce0 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63  andle.** to whic
34cf0 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  h a [prepared st
34d00 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73  atement] belongs
34d10 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73  .  ^The [databas
34d20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
34d30 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
34d40 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69  ite3_db_handle i
34d50 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  s the same [data
34d60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
34d70 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65  .** that was the
34d80 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
34d90 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
34da0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
34db0 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61   call (or its va
34dc0 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73  riants) that was
34dd0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61   used to.** crea
34de0 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
34df0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c   in the first pl
34e00 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  ace..*/.sqlite3 
34e10 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64  *sqlite3_db_hand
34e20 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
34e30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34e40 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 46  EF: Return The F
34e50 69 6c 65 6e 61 6d 65 20 46 6f 72 20 41 20 44 61  ilename For A Da
34e60 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
34e70 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  n.**.** ^The sql
34e80 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65  ite3_db_filename
34e90 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (D,N) interface 
34ea0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
34eb0 72 20 74 6f 20 61 20 66 69 6c 65 6e 61 6d 65 0a  r to a filename.
34ec0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
34ed0 74 68 20 64 61 74 61 62 61 73 65 20 4e 20 6f 66  th database N of
34ee0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
34ef0 5e 54 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61  ^The main databa
34f00 73 65 20 66 69 6c 65 0a 2a 2a 20 68 61 73 20 74  se file.** has t
34f10 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 2e 20  he name "main". 
34f20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
34f30 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
34f40 65 20 4e 20 6f 6e 20 74 68 65 20 64 61 74 61 62  e N on the datab
34f50 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
34f60 6e 20 44 2c 20 6f 72 20 69 66 20 64 61 74 61 62  n D, or if datab
34f70 61 73 65 20 4e 20 69 73 20 61 20 74 65 6d 70 6f  ase N is a tempo
34f80 72 61 72 79 20 6f 72 20 69 6e 2d 6d 65 6d 6f 72  rary or in-memor
34f90 79 20 64 61 74 61 62 61 73 65 2c 20 74 68 65 6e  y database, then
34fa0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
34fb0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
34fc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 6c 65 6e  **.** ^The filen
34fd0 61 6d 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  ame returned by 
34fe0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  this function is
34ff0 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 74   the output of t
35000 68 65 0a 2a 2a 20 78 46 75 6c 6c 50 61 74 68 6e  he.** xFullPathn
35010 61 6d 65 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ame method of th
35020 65 20 5b 56 46 53 5d 2e 20 20 5e 49 6e 20 6f 74  e [VFS].  ^In ot
35030 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 66  her words, the f
35040 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  ilename.** will 
35050 62 65 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  be an absolute p
35060 61 74 68 6e 61 6d 65 2c 20 65 76 65 6e 20 69 66  athname, even if
35070 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 75 73   the filename us
35080 65 64 0a 2a 2a 20 74 6f 20 6f 70 65 6e 20 74 68  ed.** to open th
35090 65 20 64 61 74 61 62 61 73 65 20 6f 72 69 67 69  e database origi
350a0 6e 61 6c 6c 79 20 77 61 73 20 61 20 55 52 49 20  nally was a URI 
350b0 6f 72 20 72 65 6c 61 74 69 76 65 20 70 61 74 68  or relative path
350c0 6e 61 6d 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  name..*/.const c
350d0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f  har *sqlite3_db_
350e0 66 69 6c 65 6e 61 6d 65 28 73 71 6c 69 74 65 33  filename(sqlite3
350f0 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72   *db, const char
35100 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a   *zDbName);../*.
35110 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
35120 65 72 6d 69 6e 65 20 69 66 20 61 20 64 61 74 61  ermine if a data
35130 62 61 73 65 20 69 73 20 72 65 61 64 2d 6f 6e 6c  base is read-onl
35140 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
35150 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79  ite3_db_readonly
35160 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (D,N) interface 
35170 72 65 74 75 72 6e 73 20 31 20 69 66 20 74 68 65  returns 1 if the
35180 20 64 61 74 61 62 61 73 65 20 4e 0a 2a 2a 20 6f   database N.** o
35190 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 20 69  f connection D i
351a0 73 20 72 65 61 64 2d 6f 6e 6c 79 2c 20 30 20 69  s read-only, 0 i
351b0 66 20 69 74 20 69 73 20 72 65 61 64 2f 77 72 69  f it is read/wri
351c0 74 65 2c 20 6f 72 20 2d 31 20 69 66 20 4e 20 69  te, or -1 if N i
351d0 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 6e 61 6d  s not.** the nam
351e0 65 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  e of a database 
351f0 6f 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  on connection D.
35200 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
35210 64 62 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69  db_readonly(sqli
35220 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63  te3 *db, const c
35230 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a  har *zDbName);..
35240 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
35250 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72  Find the next pr
35260 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
35270 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
35280 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
35290 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
352a0 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73  next [prepared s
352b0 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a  tatement] after.
352c0 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61  ** pStmt associa
352d0 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
352e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
352f0 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53 74  n] pDb.  ^If pSt
35300 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68  mt is NULL.** th
35310 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  en this interfac
35320 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
35330 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74  ter to the first
35340 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
35350 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ent.** associate
35360 64 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62  d with the datab
35370 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70  ase connection p
35380 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65 70  Db.  ^If no prep
35390 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
353a0 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65 20  * satisfies the 
353b0 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68  conditions of th
353c0 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72  is routine, it r
353d0 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  eturns NULL..**.
353e0 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73 65  ** The [database
353f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69   connection] poi
35400 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c  nter D in a call
35410 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
35420 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20  next_stmt(D,S)] 
35430 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e  must refer to an
35440 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a   open database.*
35450 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64  * connection and
35460 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d   in particular m
35470 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c  ust not be a NUL
35480 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71  L pointer..*/.sq
35490 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69  lite3_stmt *sqli
354a0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71  te3_next_stmt(sq
354b0 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69  lite3 *pDb, sqli
354c0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
354d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
354e0 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f  F: Commit And Ro
354f0 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74  llback Notificat
35500 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
35510 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35520 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69  _commit_hook() i
35530 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
35540 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
35550 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
35560 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
35570 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
35580 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d  s [COMMIT | comm
35590 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20  itted]..** ^Any 
355a0 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
355b0 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
355c0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  to sqlite3_commi
355d0 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20  t_hook().** for 
355e0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
355f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
35600 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e  overridden..** ^
35610 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  The sqlite3_roll
35620 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  back_hook() inte
35630 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
35640 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
35650 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
35660 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
35670 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b  transaction is [
35680 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65  ROLLBACK | rolle
35690 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79  d back]..** ^Any
356a0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
356b0 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
356c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c   to sqlite3_roll
356d0 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66  back_hook().** f
356e0 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
356f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
35700 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
35710 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72 67 75  * ^The pArg argu
35720 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74  ment is passed t
35730 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61  hrough to the ca
35740 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74  llback..** ^If t
35750 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61  he callback on a
35760 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e   commit hook fun
35770 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f  ction returns no
35780 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20  n-zero,.** then 
35790 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f  the commit is co
357a0 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72  nverted into a r
357b0 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  ollback..**.** ^
357c0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  The sqlite3_comm
357d0 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61  it_hook(D,C,P) a
357e0 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  nd sqlite3_rollb
357f0 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  ack_hook(D,C,P) 
35800 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74  functions.** ret
35810 75 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65  urn the P argume
35820 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76  nt from the prev
35830 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65  ious call of the
35840 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a   same function.*
35850 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  * on the same [d
35860 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35870 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66  on] D, or NULL f
35880 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  or.** the first 
35890 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75  call for each fu
358a0 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a  nction on D..**.
358b0 2a 2a 20 54 68 65 20 63 6f 6d 6d 69 74 20 61 6e  ** The commit an
358c0 64 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  d rollback hook 
358d0 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6e 6f  callbacks are no
358e0 74 20 72 65 65 6e 74 72 61 6e 74 2e 0a 2a 2a 20  t reentrant..** 
358f0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70  The callback imp
35900 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
35910 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
35920 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
35930 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
35940 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
35950 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61  t invoked the ca
35960 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74  llback.  Any act
35970 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66  ions.** to modif
35980 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  y the database c
35990 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62  onnection must b
359a0 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c  e deferred until
359b0 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f   after the.** co
359c0 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20  mpletion of the 
359d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
359e0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
359f0 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a  ered the commit.
35a00 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68  ** or rollback h
35a10 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74  ook in the first
35a20 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20   place..** Note 
35a30 74 68 61 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  that running any
35a40 20 6f 74 68 65 72 20 53 51 4c 20 73 74 61 74 65   other SQL state
35a50 6d 65 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67  ments, including
35a60 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
35a70 74 73 2c 0a 2a 2a 20 6f 72 20 6d 65 72 65 6c 79  ts,.** or merely
35a80 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
35a90 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
35aa0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
35ab0 70 28 29 5d 20 77 69 6c 6c 20 6d 6f 64 69 66 79  p()] will modify
35ac0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
35ad0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
35ae0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
35af0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
35b00 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
35b10 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61  * ^Registering a
35b20 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64   NULL function d
35b30 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c  isables the call
35b40 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  back..**.** ^Whe
35b50 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f  n the commit hoo
35b60 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  k callback routi
35b70 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  ne returns zero,
35b80 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a   the [COMMIT].**
35b90 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c   operation is al
35ba0 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75  lowed to continu
35bb0 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66  e normally.  ^If
35bc0 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
35bd0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  .** returns non-
35be0 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b  zero, then the [
35bf0 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65  COMMIT] is conve
35c00 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c  rted into a [ROL
35c10 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20  LBACK]..** ^The 
35c20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73  rollback hook is
35c30 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f   invoked on a ro
35c40 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75  llback that resu
35c50 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69  lts from a commi
35c60 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e  t.** hook return
35c70 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75  ing non-zero, ju
35c80 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62  st as it would b
35c90 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72  e with any other
35ca0 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
35cb0 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73   ^For the purpos
35cc0 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20  es of this API, 
35cd0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
35ce0 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65   said to have be
35cf0 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63  en.** rolled bac
35d00 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74  k if an explicit
35d10 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74   "ROLLBACK" stat
35d20 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65  ement is execute
35d30 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  d, or.** an erro
35d40 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20  r or constraint 
35d50 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63  causes an implic
35d60 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f  it rollback to o
35d70 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f  ccur..** ^The ro
35d80 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20  llback callback 
35d90 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69  is not invoked i
35da0 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  f a transaction 
35db0 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  is.** automatica
35dc0 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
35dd0 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61  because the data
35de0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
35df0 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
35e00 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
35e10 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
35e20 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ok()] interface.
35e30 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
35e40 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71  3_commit_hook(sq
35e50 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
35e60 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76  oid*), void*);.v
35e70 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c  oid *sqlite3_rol
35e80 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74  lback_hook(sqlit
35e90 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  e3*, void(*)(voi
35ea0 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  d *), void*);../
35eb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
35ec0 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66  ata Change Notif
35ed0 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
35ee0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
35ef0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
35f00 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
35f10 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
35f20 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  k function.** wi
35f30 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
35f40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65   connection] ide
35f50 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ntified by the f
35f60 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
35f70 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
35f80 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73  henever a row is
35f90 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
35fa0 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a  ed or deleted..*
35fb0 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
35fc0 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
35fd0 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66  s call to this f
35fe0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74  unction.** for t
35ff0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
36000 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
36010 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a  verridden..**.**
36020 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
36030 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
36040 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69  er to the functi
36050 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65  on to invoke whe
36060 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70  n a.** row is up
36070 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
36080 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e  or deleted..** ^
36090 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
360a0 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  nt to the callba
360b0 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
360c0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
360d0 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  nt.** to sqlite3
360e0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a  _update_hook()..
360f0 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 63  ** ^The second c
36100 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74  allback argument
36110 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
36120 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c  TE_INSERT], [SQL
36130 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20  ITE_DELETE],.** 
36140 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54  or [SQLITE_UPDAT
36150 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  E], depending on
36160 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74   the operation t
36170 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63  hat caused the c
36180 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65  allback.** to be
36190 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68   invoked..** ^Th
361a0 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
361b0 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  th arguments to 
361c0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  the callback con
361d0 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f  tain pointers to
361e0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
361f0 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20   and table name 
36200 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
36210 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20  ffected row..** 
36220 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62  ^The final callb
36230 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ack parameter is
36240 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
36250 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20  the row..** ^In 
36260 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75  the case of an u
36270 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74  pdate, this is t
36280 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 72  he [rowid] after
36290 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65   the update take
362a0 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  s place..**.** ^
362b0 28 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b  (The update hook
362c0 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
362d0 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79  when internal sy
362e0 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a  stem tables are.
362f0 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65  ** modified (i.e
36300 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20  . sqlite_master 
36310 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65  and sqlite_seque
36320 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  nce).)^.**.** ^I
36330 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  n the current im
36340 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68  plementation, th
36350 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a  e update hook.**
36360 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
36370 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e  when duplication
36380 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
36390 64 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a  d because of an.
363a0 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20  ** [ON CONFLICT 
363b0 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45  | ON CONFLICT RE
363c0 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20  PLACE] clause.  
363d0 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64 61  ^Nor is the upda
363e0 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b  te hook.** invok
363f0 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65  ed when rows are
36400 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74   deleted using t
36410 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  he [truncate opt
36420 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  imization]..** T
36430 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65  he exceptions de
36440 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61  fined in this pa
36450 72 61 67 72 61 70 68 20 6d 69 67 68 74 20 63 68  ragraph might ch
36460 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65  ange in a future
36470 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53  .** release of S
36480 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
36490 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70   update hook imp
364a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
364b0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
364c0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
364d0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
364e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
364f0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70  t invoked the up
36500 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20  date hook.  Any 
36510 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f  actions.** to mo
36520 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
36530 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
36540 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e  t be deferred un
36550 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a  til after the.**
36560 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74   completion of t
36570 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
36580 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ()] call that tr
36590 69 67 67 65 72 65 64 20 74 68 65 20 75 70 64 61  iggered the upda
365a0 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65  te hook..** Note
365b0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
365c0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
365d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
365e0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
365f0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
36600 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
36610 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
36620 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
36630 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
36640 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70   ^The sqlite3_up
36650 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  date_hook(D,C,P)
36660 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 74   function.** ret
36670 75 72 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d  urns the P argum
36680 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
36690 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e  vious call.** on
366a0 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
366b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
366c0 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a  D, or NULL for.*
366d0 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  * the first call
366e0 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   on D..**.** See
366f0 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
36700 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
36710 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  ], [sqlite3_roll
36720 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 2c 0a 2a 2a  back_hook()],.**
36730 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
36740 65 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20  eupdate_hook()] 
36750 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 76  interfaces..*/.v
36760 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64  oid *sqlite3_upd
36770 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69  ate_hook(.  sqli
36780 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  te3*, .  void(*)
36790 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61  (void *,int ,cha
367a0 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63  r const *,char c
367b0 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69  onst *,sqlite3_i
367c0 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29  nt64),.  void*.)
367d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
367e0 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
367f0 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 65  able Shared Page
36800 72 20 43 61 63 68 65 0a 2a 2a 20 4b 45 59 57 4f  r Cache.** KEYWO
36810 52 44 53 3a 20 7b 73 68 61 72 65 64 20 63 61 63  RDS: {shared cac
36820 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  he}.**.** ^(This
36830 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
36840 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
36850 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20   sharing of the 
36860 64 61 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a  database cache.*
36870 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74  * and schema dat
36880 61 20 73 74 72 75 63 74 75 72 65 73 20 62 65 74  a structures bet
36890 77 65 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  ween [database c
368a0 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e  onnection | conn
368b0 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74  ections].** to t
368c0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
368d0 2e 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61  . Sharing is ena
368e0 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75  bled if the argu
368f0 6d 65 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a 20  ment is true.** 
36900 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20  and disabled if 
36910 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  the argument is 
36920 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  false.)^.**.** ^
36930 43 61 63 68 65 20 73 68 61 72 69 6e 67 20 69 73  Cache sharing is
36940 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73   enabled and dis
36950 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e 74  abled for an ent
36960 69 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20  ire process..** 
36970 54 68 69 73 20 69 73 20 61 20 63 68 61 6e 67 65  This is a change
36980 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65   as of SQLite ve
36990 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20  rsion 3.5.0. In 
369a0 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f  prior versions o
369b0 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61  f SQLite,.** sha
369c0 72 69 6e 67 20 77 61 73 20 65 6e 61 62 6c 65 64  ring was enabled
369d0 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72   or disabled for
369e0 20 65 61 63 68 20 74 68 72 65 61 64 20 73 65 70   each thread sep
369f0 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  arately..**.** ^
36a00 28 54 68 65 20 63 61 63 68 65 20 73 68 61 72 69  (The cache shari
36a10 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74  ng mode set by t
36a20 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65 66  his interface ef
36a30 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71  fects all subseq
36a40 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
36a50 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
36a60 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
36a70 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  _v2()], and [sql
36a80 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
36a90 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74 61  ** Existing data
36aa0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
36ab0 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68   continue use th
36ac0 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a  e sharing mode.*
36ad0 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 65 66  * that was in ef
36ae0 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d 65  fect at the time
36af0 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65   they were opene
36b00 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  d.)^.**.** ^(Thi
36b10 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
36b20 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66  s [SQLITE_OK] if
36b30 20 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61   shared cache wa
36b40 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  s enabled or dis
36b50 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73  abled.** success
36b60 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f  fully.  An [erro
36b70 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
36b80 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e 29 5e  ned otherwise.)^
36b90 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65 64 20 63  .**.** ^Shared c
36ba0 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64  ache is disabled
36bb0 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74   by default. But
36bc0 20 74 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e   this might chan
36bd0 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  ge in.** future 
36be0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
36bf0 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  te.  Application
36c00 73 20 74 68 61 74 20 63 61 72 65 20 61 62 6f 75  s that care abou
36c10 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
36c20 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64  e setting should
36c30 20 73 65 74 20 69 74 20 65 78 70 6c 69 63 69 74   set it explicit
36c40 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c  ly..**.** See Al
36c50 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53 68 61  so:  [SQLite Sha
36c60 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d 0a  red-Cache Mode].
36c70 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
36c80 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
36c90 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  he(int);../*.** 
36ca0 43 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70  CAPI3REF: Attemp
36cb0 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d  t To Free Heap M
36cc0 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  emory.**.** ^The
36cd0 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
36ce0 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66  _memory() interf
36cf0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
36d00 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20  free N bytes.** 
36d10 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62  of heap memory b
36d20 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e  y deallocating n
36d30 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d  on-essential mem
36d40 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a  ory allocations.
36d50 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20 64  ** held by the d
36d60 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e  atabase library.
36d70 20 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 74     Memory used t
36d80 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73 65  o cache database
36d90 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d 70  .** pages to imp
36da0 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  rove performance
36db0 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   is an example o
36dc0 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20  f non-essential 
36dd0 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c 69  memory..** ^sqli
36de0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
36df0 72 79 28 29 20 72 65 74 75 72 6e 73 20 74 68 65  ry() returns the
36e00 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
36e10 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c   actually freed,
36e20 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74 20  .** which might 
36e30 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20  be more or less 
36e40 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  than the amount 
36e50 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 20 5e 54  requested..** ^T
36e60 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  he sqlite3_relea
36e70 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 6f 75 74  se_memory() rout
36e80 69 6e 65 20 69 73 20 61 20 6e 6f 2d 6f 70 20 72  ine is a no-op r
36e90 65 74 75 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a 2a  eturning zero.**
36ea0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 6e 6f   if SQLite is no
36eb0 74 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  t compiled with 
36ec0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
36ed0 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54  EMORY_MANAGEMENT
36ee0 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
36ef0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 72  o: [sqlite3_db_r
36f00 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
36f10 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
36f20 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69  release_memory(i
36f30 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
36f40 33 52 45 46 3a 20 46 72 65 65 20 4d 65 6d 6f 72  3REF: Free Memor
36f50 79 20 55 73 65 64 20 42 79 20 41 20 44 61 74 61  y Used By A Data
36f60 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
36f70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36f80 65 33 5f 64 62 5f 72 65 6c 65 61 73 65 5f 6d 65  e3_db_release_me
36f90 6d 6f 72 79 28 44 29 20 69 6e 74 65 72 66 61 63  mory(D) interfac
36fa0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72  e attempts to fr
36fb0 65 65 20 61 73 20 6d 75 63 68 20 68 65 61 70 0a  ee as much heap.
36fc0 2a 2a 20 6d 65 6d 6f 72 79 20 61 73 20 70 6f 73  ** memory as pos
36fd0 73 69 62 6c 65 20 66 72 6f 6d 20 64 61 74 61 62  sible from datab
36fe0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
36ff0 2e 20 55 6e 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  . Unlike the.** 
37000 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
37010 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 6e 74 65 72  _memory()] inter
37020 66 61 63 65 2c 20 74 68 69 73 20 69 6e 74 65 72  face, this inter
37030 66 61 63 65 20 69 73 20 65 66 66 65 63 74 20 65  face is effect e
37040 76 65 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 6e  ven.** when then
37050 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
37060 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e  MEMORY_MANAGEMEN
37070 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
37080 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f 6d 69  option is.** omi
37090 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  tted..**.** See 
370a0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 72  also: [sqlite3_r
370b0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
370c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
370d0 64 62 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  db_release_memor
370e0 79 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  y(sqlite3*);../*
370f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6d  .** CAPI3REF: Im
37100 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20  pose A Limit On 
37110 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20  Heap Size.**.** 
37120 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66  ^The sqlite3_sof
37130 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
37140 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
37150 61 6e 64 2f 6f 72 20 71 75 65 72 69 65 73 20 74  and/or queries t
37160 68 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d 69 74  he.** soft limit
37170 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f   on the amount o
37180 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68  f heap memory th
37190 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61  at may be alloca
371a0 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
371b0 2a 20 5e 53 51 4c 69 74 65 20 73 74 72 69 76 65  * ^SQLite strive
371c0 73 20 74 6f 20 6b 65 65 70 20 68 65 61 70 20 6d  s to keep heap m
371d0 65 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74 69 6f  emory utilizatio
371e0 6e 20 62 65 6c 6f 77 20 74 68 65 20 73 6f 66 74  n below the soft
371f0 20 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74 20 62   heap.** limit b
37200 79 20 72 65 64 75 63 69 6e 67 20 74 68 65 20 6e  y reducing the n
37210 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 68  umber of pages h
37220 65 6c 64 20 69 6e 20 74 68 65 20 70 61 67 65 20  eld in the page 
37230 63 61 63 68 65 0a 2a 2a 20 61 73 20 68 65 61 70  cache.** as heap
37240 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 73 20 61   memory usages a
37250 70 70 72 6f 61 63 68 65 73 20 74 68 65 20 6c 69  pproaches the li
37260 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f 66  mit..** ^The sof
37270 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
37280 22 73 6f 66 74 22 20 62 65 63 61 75 73 65 20 65  "soft" because e
37290 76 65 6e 20 74 68 6f 75 67 68 20 53 51 4c 69 74  ven though SQLit
372a0 65 20 73 74 72 69 76 65 73 20 74 6f 20 73 74 61  e strives to sta
372b0 79 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65 20 6c  y.** below the l
372c0 69 6d 69 74 2c 20 69 74 20 77 69 6c 6c 20 65 78  imit, it will ex
372d0 63 65 65 64 20 74 68 65 20 6c 69 6d 69 74 20 72  ceed the limit r
372e0 61 74 68 65 72 20 74 68 61 6e 20 67 65 6e 65 72  ather than gener
372f0 61 74 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49 54  ate.** an [SQLIT
37300 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e 20  E_NOMEM] error. 
37310 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
37320 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
37330 69 6d 69 74 20 0a 2a 2a 20 69 73 20 61 64 76 69  imit .** is advi
37340 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  sory only..**.**
37350 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c   ^The return val
37360 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
37370 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
37380 34 28 29 20 69 73 20 74 68 65 20 73 69 7a 65 20  4() is the size 
37390 6f 66 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20 68  of.** the soft h
373a0 65 61 70 20 6c 69 6d 69 74 20 70 72 69 6f 72 20  eap limit prior 
373b0 74 6f 20 74 68 65 20 63 61 6c 6c 2c 20 6f 72 20  to the call, or 
373c0 6e 65 67 61 74 69 76 65 20 69 6e 20 74 68 65 20  negative in the 
373d0 63 61 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 65 72  case of an.** er
373e0 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 72  ror.  ^If the ar
373f0 67 75 6d 65 6e 74 20 4e 20 69 73 20 6e 65 67 61  gument N is nega
37400 74 69 76 65 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20  tive.** then no 
37410 63 68 61 6e 67 65 20 69 73 20 6d 61 64 65 20 74  change is made t
37420 6f 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  o the soft heap 
37430 6c 69 6d 69 74 2e 20 20 48 65 6e 63 65 2c 20 74  limit.  Hence, t
37440 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 73 69  he current.** si
37450 7a 65 20 6f 66 20 74 68 65 20 73 6f 66 74 20 68  ze of the soft h
37460 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 20 62 65  eap limit can be
37470 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 69   determined by i
37480 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  nvoking.** sqlit
37490 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
374a0 69 74 36 34 28 29 20 77 69 74 68 20 61 20 6e 65  it64() with a ne
374b0 67 61 74 69 76 65 20 61 72 67 75 6d 65 6e 74 2e  gative argument.
374c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
374d0 72 67 75 6d 65 6e 74 20 4e 20 69 73 20 7a 65 72  rgument N is zer
374e0 6f 20 74 68 65 6e 20 74 68 65 20 73 6f 66 74 20  o then the soft 
374f0 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 64 69  heap limit is di
37500 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  sabled..**.** ^(
37510 54 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  The soft heap li
37520 6d 69 74 20 69 73 20 6e 6f 74 20 65 6e 66 6f 72  mit is not enfor
37530 63 65 64 20 69 6e 20 74 68 65 20 63 75 72 72 65  ced in the curre
37540 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
37550 6e 0a 2a 2a 20 69 66 20 6f 6e 65 20 6f 72 20 6d  n.** if one or m
37560 6f 72 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  ore of following
37570 20 63 6f 6e 64 69 74 69 6f 6e 73 20 61 72 65 20   conditions are 
37580 74 72 75 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  true:.**.** <ul>
37590 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 73 6f 66  .** <li> The sof
375a0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
375b0 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 20  set to zero..** 
375c0 3c 6c 69 3e 20 4d 65 6d 6f 72 79 20 61 63 63 6f  <li> Memory acco
375d0 75 6e 74 69 6e 67 20 69 73 20 64 69 73 61 62 6c  unting is disabl
375e0 65 64 20 75 73 69 6e 67 20 61 20 63 6f 6d 62 69  ed using a combi
375f0 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  nation of the.**
37600 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
37610 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
37620 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
37630 2c 2e 2e 2e 29 20 73 74 61 72 74 2d 74 69 6d 65  ,...) start-time
37640 20 6f 70 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20   option and.**  
37650 20 20 20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f      the [SQLITE_
37660 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
37670 53 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  S] compile-time 
37680 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20  option..** <li> 
37690 41 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 20 70  An alternative p
376a0 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
376b0 65 6e 74 61 74 69 6f 6e 20 69 73 20 73 70 65 63  entation is spec
376c0 69 66 69 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20  ified using.**  
376d0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e      [sqlite3_con
376e0 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
376f0 46 49 47 5f 50 43 41 43 48 45 32 5d 2c 2e 2e 2e  FIG_PCACHE2],...
37700 29 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 70  )..** <li> The p
37710 61 67 65 20 63 61 63 68 65 20 61 6c 6c 6f 63 61  age cache alloca
37720 74 65 73 20 66 72 6f 6d 20 69 74 73 20 6f 77 6e  tes from its own
37730 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 20 73 75 70   memory pool sup
37740 70 6c 69 65 64 0a 2a 2a 20 20 20 20 20 20 62 79  plied.**      by
37750 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
37760 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
37770 5f 50 41 47 45 43 41 43 48 45 5d 2c 2e 2e 2e 29  _PAGECACHE],...)
37780 20 72 61 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20   rather than.** 
37790 20 20 20 20 20 66 72 6f 6d 20 74 68 65 20 68 65       from the he
377a0 61 70 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  ap..** </ul>)^.*
377b0 2a 0a 2a 2a 20 42 65 67 69 6e 6e 69 6e 67 20 77  *.** Beginning w
377c0 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69  ith SQLite versi
377d0 6f 6e 20 33 2e 37 2e 33 2c 20 74 68 65 20 73 6f  on 3.7.3, the so
377e0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
377f0 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 72 65 67   enforced.** reg
37800 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
37810 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53  er or not the [S
37820 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
37830 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 0a  ORY_MANAGEMENT].
37840 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
37850 6f 70 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  option is invoke
37860 64 2e 20 20 57 69 74 68 20 5b 53 51 4c 49 54 45  d.  With [SQLITE
37870 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d  _ENABLE_MEMORY_M
37880 41 4e 41 47 45 4d 45 4e 54 5d 2c 0a 2a 2a 20 74  ANAGEMENT],.** t
37890 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
378a0 69 74 20 69 73 20 65 6e 66 6f 72 63 65 64 20 6f  it is enforced o
378b0 6e 20 65 76 65 72 79 20 6d 65 6d 6f 72 79 20 61  n every memory a
378c0 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 57 69 74 68  llocation.  With
378d0 6f 75 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  out.** [SQLITE_E
378e0 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e  NABLE_MEMORY_MAN
378f0 41 47 45 4d 45 4e 54 5d 2c 20 74 68 65 20 73 6f  AGEMENT], the so
37900 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
37910 20 6f 6e 6c 79 20 65 6e 66 6f 72 63 65 64 0a 2a   only enforced.*
37920 2a 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73  * when memory is
37930 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 74 68   allocated by th
37940 65 20 70 61 67 65 20 63 61 63 68 65 2e 20 20 54  e page cache.  T
37950 65 73 74 69 6e 67 20 73 75 67 67 65 73 74 73 20  esting suggests 
37960 74 68 61 74 20 62 65 63 61 75 73 65 0a 2a 2a 20  that because.** 
37970 74 68 65 20 70 61 67 65 20 63 61 63 68 65 20 69  the page cache i
37980 73 20 74 68 65 20 70 72 65 64 6f 6d 69 6e 61 74  s the predominat
37990 65 20 6d 65 6d 6f 72 79 20 75 73 65 72 20 69 6e  e memory user in
379a0 20 53 51 4c 69 74 65 2c 20 6d 6f 73 74 0a 2a 2a   SQLite, most.**
379b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
379c0 6c 6c 20 61 63 68 69 65 76 65 20 61 64 65 71 75  ll achieve adequ
379d0 61 74 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  ate soft heap li
379e0 6d 69 74 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20  mit enforcement 
379f0 77 69 74 68 6f 75 74 0a 2a 2a 20 74 68 65 20 75  without.** the u
37a00 73 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 4e  se of [SQLITE_EN
37a10 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41  ABLE_MEMORY_MANA
37a20 47 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 54  GEMENT]..**.** T
37a30 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  he circumstances
37a40 20 75 6e 64 65 72 20 77 68 69 63 68 20 53 51 4c   under which SQL
37a50 69 74 65 20 77 69 6c 6c 20 65 6e 66 6f 72 63 65  ite will enforce
37a60 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
37a70 69 6d 69 74 20 6d 61 79 0a 2a 2a 20 63 68 61 6e  imit may.** chan
37a80 67 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  ges in future re
37a90 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
37aa0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
37ab0 36 34 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  64 sqlite3_soft_
37ac0 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 73 71 6c  heap_limit64(sql
37ad0 69 74 65 33 5f 69 6e 74 36 34 20 4e 29 3b 0a 0a  ite3_int64 N);..
37ae0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37af0 44 65 70 72 65 63 61 74 65 64 20 53 6f 66 74 20  Deprecated Soft 
37b00 48 65 61 70 20 4c 69 6d 69 74 20 49 6e 74 65 72  Heap Limit Inter
37b10 66 61 63 65 0a 2a 2a 20 44 45 50 52 45 43 41 54  face.** DEPRECAT
37b20 45 44 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  ED.**.** This is
37b30 20 61 20 64 65 70 72 65 63 61 74 65 64 20 76 65   a deprecated ve
37b40 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71  rsion of the [sq
37b50 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
37b60 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 69 6e  limit64()].** in
37b70 74 65 72 66 61 63 65 2e 20 20 54 68 69 73 20 72  terface.  This r
37b80 6f 75 74 69 6e 65 20 69 73 20 70 72 6f 76 69 64  outine is provid
37b90 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  ed for historica
37ba0 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a  l compatibility.
37bb0 2a 2a 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6e 65  ** only.  All ne
37bc0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
37bd0 68 6f 75 6c 64 20 75 73 65 20 74 68 65 0a 2a 2a  hould use the.**
37be0 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
37bf0 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 20 69  eap_limit64()] i
37c00 6e 74 65 72 66 61 63 65 20 72 61 74 68 65 72 20  nterface rather 
37c10 74 68 61 6e 20 74 68 69 73 20 6f 6e 65 2e 0a 2a  than this one..*
37c20 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  /.SQLITE_DEPRECA
37c30 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33  TED void sqlite3
37c40 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
37c50 28 69 6e 74 20 4e 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  (int N);.../*.**
37c60 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 72 61   CAPI3REF: Extra
37c70 63 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75  ct Metadata Abou
37c80 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20  t A Column Of A 
37c90 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  Table.**.** ^Thi
37ca0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
37cb0 73 20 6d 65 74 61 64 61 74 61 20 61 62 6f 75 74  s metadata about
37cc0 20 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75   a specific colu
37cd0 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69 63  mn of a specific
37ce0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 74 61 62  .** database tab
37cf0 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20 75 73  le accessible us
37d00 69 6e 67 20 74 68 65 20 5b 64 61 74 61 62 61 73  ing the [databas
37d10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
37d20 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20 61  ndle.** passed a
37d30 73 20 74 68 65 20 66 69 72 73 74 20 66 75 6e 63  s the first func
37d40 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
37d50 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e  *.** ^The column
37d60 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62   is identified b
37d70 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68  y the second, th
37d80 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
37d90 61 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20  arameters to.** 
37da0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e  this function. ^
37db0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
37dc0 65 74 65 72 20 69 73 20 65 69 74 68 65 72 20 74  eter is either t
37dd0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
37de0 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e  atabase.** (i.e.
37df0 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c   "main", "temp",
37e00 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64 20   or an attached 
37e10 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69  database) contai
37e20 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69 66 69  ning the specifi
37e30 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e  ed.** table or N
37e40 55 4c 4c 2e 20 5e 49 66 20 69 74 20 69 73 20 4e  ULL. ^If it is N
37e50 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74  ULL, then all at
37e60 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
37e70 20 61 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a   are searched.**
37e80 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75   for the table u
37e90 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c  sing the same al
37ea0 67 6f 72 69 74 68 6d 20 75 73 65 64 20 62 79 20  gorithm used by 
37eb0 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
37ec0 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76  ine to.** resolv
37ed0 65 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61  e unqualified ta
37ee0 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a  ble references..
37ef0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
37f00 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61   and fourth para
37f10 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66  meters to this f
37f20 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20  unction are the 
37f30 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e  table and column
37f40 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  .** name of the 
37f50 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20  desired column, 
37f60 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65  respectively. Ne
37f70 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 70  ither of these p
37f80 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79  arameters.** may
37f90 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
37fa0 5e 4d 65 74 61 64 61 74 61 20 69 73 20 72 65 74  ^Metadata is ret
37fb0 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67  urned by writing
37fc0 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c   to the memory l
37fd0 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20  ocations passed 
37fe0 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e  as the 5th.** an
37ff0 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72  d subsequent par
38000 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20  ameters to this 
38010 66 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f  function. ^Any o
38020 66 20 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74  f these argument
38030 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c  s may be.** NULL
38040 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  , in which case 
38050 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
38060 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74  g element of met
38070 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64  adata is omitted
38080 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b  ..**.** ^(<block
38090 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
380a0 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
380b0 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74  <tr><th> Paramet
380c0 65 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62  er <th> Output<b
380d0 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73  r>Type <th>  Des
380e0 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  cription.**.** <
380f0 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e  tr><td> 5th <td>
38100 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64   const char* <td
38110 3e 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c  > Data type.** <
38120 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e  tr><td> 6th <td>
38130 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64   const char* <td
38140 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c  > Name of defaul
38150 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  t collation sequ
38160 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ence.** <tr><td>
38170 20 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20   7th <td> int   
38180 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20        <td> True 
38190 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20  if column has a 
381a0 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61  NOT NULL constra
381b0 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  int.** <tr><td> 
381c0 38 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20  8th <td> int    
381d0 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69       <td> True i
381e0 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74  f column is part
381f0 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20   of the PRIMARY 
38200 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  KEY.** <tr><td> 
38210 39 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20  9th <td> int    
38220 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69       <td> True i
38230 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54  f column is [AUT
38240 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c  OINCREMENT].** <
38250 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
38260 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
38270 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   ^The memory poi
38280 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 63  nted to by the c
38290 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72  haracter pointer
382a0 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74  s returned for t
382b0 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f  he.** declaratio
382c0 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61  n type and colla
382d0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
382e0 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69   valid only unti
382f0 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61  l the next.** ca
38300 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65  ll to any SQLite
38310 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   API function..*
38320 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  *.** ^If the spe
38330 63 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20  cified table is 
38340 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c  actually a view,
38350 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
38360 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
38370 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
38380 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20  ified column is 
38390 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f  "rowid", "oid" o
383a0 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20  r "_rowid_" and 
383b0 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50  an.** [INTEGER P
383c0 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75  RIMARY KEY] colu
383d0 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c  mn has been expl
383e0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c  icitly declared,
383f0 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74   then the output
38400 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61  .** parameters a
38410 72 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65  re set for the e
38420 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
38430 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20  ed column. ^(If 
38440 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65  there is no.** e
38450 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
38460 65 64 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  ed [INTEGER PRIM
38470 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c  ARY KEY] column,
38480 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74   then the output
38490 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61  .** parameters a
384a0 72 65 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77  re set as follow
384b0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a  s:.**.** <pre>.*
384c0 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 65 3a  *     data type:
384d0 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20   "INTEGER".**   
384e0 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75    collation sequ
384f0 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a  ence: "BINARY".*
38500 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20  *     not null: 
38510 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79  0.**     primary
38520 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61   key: 1.**     a
38530 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30  uto increment: 0
38540 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a  .** </pre>)^.**.
38550 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69  ** ^(This functi
38560 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20  on may load one 
38570 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20  or more schemas 
38580 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69  from database fi
38590 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72  les. If an.** er
385a0 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
385b0 67 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20  g this process, 
385c0 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 65 73  or if the reques
385d0 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c  ted table or col
385e0 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65  umn.** cannot be
385f0 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f   found, an [erro
38600 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
38610 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72  ned and an error
38620 20 6d 65 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a   message left.**
38630 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   in the [databas
38640 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
38650 6f 20 62 65 20 72 65 74 72 69 65 76 65 64 20 75  o be retrieved u
38660 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72  sing sqlite3_err
38670 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  msg()).)^.**.** 
38680 5e 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c  ^This API is onl
38690 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
386a0 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
386b0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
386c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
386d0 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
386e0 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
386f0 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  or symbol define
38700 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
38710 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d  3_table_column_m
38720 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74  etadata(.  sqlit
38730 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
38740 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63         /* Connec
38750 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  tion handle */. 
38760 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
38770 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20  Name,        /* 
38780 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72  Database name or
38790 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74   NULL */.  const
387a0 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d   char *zTableNam
387b0 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20  e,     /* Table 
387c0 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  name */.  const 
387d0 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d  char *zColumnNam
387e0 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20  e,    /* Column 
387f0 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63  name */.  char c
38800 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70  onst **pzDataTyp
38810 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a  e,    /* OUTPUT:
38820 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 74   Declared data t
3