/ Hex Artifact Content
Login

Artifact a16fe2a826ee58e7cb0cd19bc68d33ba29ac941c:


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 65 64 20  y are supported 
07d0: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
07e0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
07f0: 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  nly.  Applicatio
0800: 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64  n writers should
0810: 20 62 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a   be aware that.*
0820: 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69  * experimental i
0830: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73 75  nterfaces are su
0840: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
0850: 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65  in point release
0860: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d  s..**.** These m
0870: 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65  acros used to re
0880: 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73  solve to various
0890: 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c   kinds of compil
08a0: 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a  er magic that.**
08b0: 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20   would generate 
08c0: 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73  warning messages
08d0: 20 77 68 65 6e 20 74 68 65 79 20 77 65 72 65 20   when they were 
08e0: 75 73 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a  used.  But that.
08f0: 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69  ** compiler magi
0900: 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72  c ended up gener
0910: 61 74 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75  ating such a flu
0920: 72 72 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72  rry of bug repor
0930: 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61  ts.** that we ha
0940: 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20  ve taken it all 
0950: 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63  out and gone bac
0960: 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c  k to using simpl
0970: 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73  e.** noop macros
0980: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
0990: 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23  ITE_DEPRECATED.#
09a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58  define SQLITE_EX
09b0: 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a  PERIMENTAL../*.*
09c0: 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65 20 73  * Ensure these s
09d0: 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20  ymbols were not 
09e0: 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20  defined by some 
09f0: 70 72 65 76 69 6f 75 73 20 68 65 61 64 65 72 20  previous header 
0a00: 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  file..*/.#ifdef 
0a10: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23  SQLITE_VERSION.#
0a20: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0a30: 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66  RSION.#endif.#if
0a40: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0a50: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65  ON_NUMBER.# unde
0a60: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a70: 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a  _NUMBER.#endif..
0a80: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
0a90: 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62  Compile-Time Lib
0aa0: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
0ab0: 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  bers.**.** ^(The
0ac0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ad0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0ae0: 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71   macro in the sq
0af0: 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a  lite3.h header.*
0b00: 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61  * evaluates to a
0b10: 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20   string literal 
0b20: 74 68 61 74 20 69 73 20 74 68 65 20 53 51 4c 69  that is the SQLi
0b30: 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68  te version in th
0b40: 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59  e.** format "X.Y
0b50: 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73 20 74  .Z" where X is t
0b60: 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e  he major version
0b70: 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20   number (always 
0b80: 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33  3 for.** SQLite3
0b90: 29 20 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d  ) and Y is the m
0ba0: 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d  inor version num
0bb0: 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65  ber and Z is the
0bc0: 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e   release number.
0bd0: 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  )^.** ^(The [SQL
0be0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bf0: 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ER] C preprocess
0c00: 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65  or macro resolve
0c10: 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a  s to an integer.
0c20: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61 6c 75  ** with the valu
0c30: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59  e (X*1000000 + Y
0c40: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65  *1000 + Z) where
0c50: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65   X, Y, and Z are
0c60: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d   the same.** num
0c70: 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51  bers used in [SQ
0c80: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e  LITE_VERSION].)^
0c90: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56  .** The SQLITE_V
0ca0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f  ERSION_NUMBER fo
0cb0: 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65  r any given rele
0cc0: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ase of SQLite wi
0cd0: 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61  ll also.** be la
0ce0: 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 72 65  rger than the re
0cf0: 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68  lease from which
0d00: 20 69 74 20 69 73 20 64 65 72 69 76 65 64 2e 20   it is derived. 
0d10: 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a   Either Y will.*
0d20: 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61  * be held consta
0d30: 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  nt and Z will be
0d40: 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20   incremented or 
0d50: 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69  else Y will be i
0d60: 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e  ncremented.** an
0d70: 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65  d Z will be rese
0d80: 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  t to zero..**.**
0d90: 20 53 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33   Since version 3
0da0: 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f  .6.18, SQLite so
0db0: 75 72 63 65 20 63 6f 64 65 20 68 61 73 20 62 65  urce code has be
0dc0: 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65  en stored in the
0dd0: 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74  .** <a href="htt
0de0: 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73  p://www.fossil-s
0df0: 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20  cm.org/">Fossil 
0e00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0e10: 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74  nagement.** syst
0e20: 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51  em</a>.  ^The SQ
0e30: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d  LITE_SOURCE_ID m
0e40: 61 63 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74  acro evaluates t
0e50: 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68  o.** a string wh
0e60: 69 63 68 20 69 64 65 6e 74 69 66 69 65 73 20 61  ich identifies a
0e70: 20 70 61 72 74 69 63 75 6c 61 72 20 63 68 65 63   particular chec
0e80: 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a  k-in of SQLite.*
0e90: 2a 20 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e  * within its con
0ea0: 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67  figuration manag
0eb0: 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e  ement system.  ^
0ec0: 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  The SQLITE_SOURC
0ed0: 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63  E_ID.** string c
0ee0: 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 65  ontains the date
0ef0: 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65   and time of the
0f00: 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20   check-in (UTC) 
0f10: 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68  and an SHA1.** h
0f20: 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72  ash of the entir
0f30: 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a  e source tree..*
0f40: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
0f50: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
0f60: 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  on()],.** [sqlit
0f70: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
0f80: 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65  mber()], [sqlite
0f90: 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a  3_sourceid()],.*
0fa0: 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f  * [sqlite_versio
0fb0: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
0fc0: 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a  _source_id()]..*
0fd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
0fe0: 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20  _VERSION        
0ff0: 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69  "--VERS--".#defi
1000: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
1010: 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49  N_NUMBER --VERSI
1020: 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66  ON-NUMBER--.#def
1030: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  ine SQLITE_SOURC
1040: 45 5f 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55  E_ID      "--SOU
1050: 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a  RCE-ID--"../*.**
1060: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
1070: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
1080: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b  ion Numbers.** K
1090: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
10a0: 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65  _version, sqlite
10b0: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a  3_sourceid.**.**
10c0: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   These interface
10d0: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
10e0: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
10f0: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
1100: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  RSION],.** [SQLI
1110: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1120: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  R], and [SQLITE_
1130: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1140: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73  processor macros
1150: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f  .** but are asso
1160: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1170: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
1180: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
1190: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a  le.  ^(Cautious.
11a0: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  ** programmers m
11b0: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73  ight include ass
11c0: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
11d0: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63   in their applic
11e0: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69  ation to.** veri
11f0: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72  fy that values r
1200: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1210: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63   interfaces matc
1220: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a  h the macros in.
1230: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61  ** the header, a
1240: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74  nd thus insure t
1250: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  hat the applicat
1260: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ion is.** compil
1270: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67  ed with matching
1280: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61   library and hea
1290: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  der files..**.**
12a0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
12b0: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71  e>.** assert( sq
12c0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
12d0: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54  _number()==SQLIT
12e0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
12f0: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73   );.** assert( s
1300: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f  trcmp(sqlite3_so
1310: 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f  urceid(),SQLITE_
1320: 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b  SOURCE_ID)==0 );
1330: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1340: 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  mp(sqlite3_libve
1350: 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56  rsion(),SQLITE_V
1360: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
1370: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1380: 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
1390: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
13a0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
13b0: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ant contains the
13c0: 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45   text of [SQLITE
13d0: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63  _VERSION].** mac
13e0: 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ro.  ^The sqlite
13f0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
1400: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1410: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1420: 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74  .** to the sqlit
1430: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1440: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54  ing constant.  T
1450: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
1460: 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74  rsion().** funct
1470: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
1480: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
1490: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
14a0: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
14b0: 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63  ave.** direct ac
14c0: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63  cess to string c
14d0: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
14e0: 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a  the DLL.  ^The.*
14f0: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
1500: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75  sion_number() fu
1510: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1520: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
1530: 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  to.** [SQLITE_VE
1540: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20  RSION_NUMBER].  
1550: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75  ^The sqlite3_sou
1560: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e  rceid() function
1570: 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70   returns .** a p
1580: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
1590: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73  ng constant whos
15a0: 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73  e value is the s
15b0: 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b  ame as the .** [
15c0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
15d0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
15e0: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65   macro..**.** Se
15f0: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f  e also: [sqlite_
1600: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
1610: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
1620: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ()]..*/.SQLITE_E
1630: 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72  XTERN const char
1640: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
1650: 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  [];.const char *
1660: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1670: 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20  on(void);.const 
1680: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f  char *sqlite3_so
1690: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e  urceid(void);.in
16a0: 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  t sqlite3_libver
16b0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64  sion_number(void
16c0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16d0: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
16e0: 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e  rary Compilation
16f0: 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73   Options Diagnos
1700: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tics.**.** ^The 
1710: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1720: 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e  ption_used() fun
1730: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20  ction returns 0 
1740: 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74  or 1 .** indicat
1750: 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 20  ing whether the 
1760: 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e  specified option
1770: 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 20   was defined at 
1780: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  .** compile time
1790: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20  .  ^The SQLITE_ 
17a0: 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d  prefix may be om
17b0: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a  itted from the .
17c0: 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70  ** option name p
17d0: 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33  assed to sqlite3
17e0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
17f0: 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e  sed().  .**.** ^
1800: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
1810: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1820: 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  function allows 
1830: 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65  iterating.** ove
1840: 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70  r the list of op
1850: 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20  tions that were 
1860: 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69  defined at compi
1870: 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65  le time by.** re
1880: 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68  turning the N-th
1890: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70   compile time op
18a0: 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49  tion string.  ^I
18b0: 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  f N is out of ra
18c0: 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  nge,.** sqlite3_
18d0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
18e0: 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  t() returns a NU
18f0: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
1900: 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72  e SQLITE_ .** pr
1910: 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20  efix is omitted 
1920: 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73  from any strings
1930: 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a   returned by .**
1940: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1950: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a  option_get()..**
1960: 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72  .** ^Support for
1970: 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20   the diagnostic 
1980: 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65  functions sqlite
1990: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
19a0: 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71  used().** and sq
19b0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
19c0: 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65  ion_get() may be
19d0: 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 63   omitted by spec
19e0: 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b  ifying the .** [
19f0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
1a00: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d  ILEOPTION_DIAGS]
1a10: 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69   option at compi
1a20: 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53  le time..**.** S
1a30: 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e  ee also: SQL fun
1a40: 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63  ctions [sqlite_c
1a50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1a60: 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1a70: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1a80: 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65  n_get()] and the
1a90: 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e   [compile_option
1aa0: 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69  s pragma]..*/.#i
1ab0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
1ac0: 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f  T_COMPILEOPTION_
1ad0: 44 49 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65  DIAGS.int sqlite
1ae0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1af0: 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20  used(const char 
1b00: 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73  *zOptName);.cons
1b10: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1b20: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b30: 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66  t(int N);.#endif
1b40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b50: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66  : Test To See If
1b60: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20   The Library Is 
1b70: 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a  Threadsafe.**.**
1b80: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68   ^The sqlite3_th
1b90: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
1ba0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ion returns zero
1bb0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
1bc0: 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f  ** SQLite was co
1bd0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65  mpiled with mute
1be0: 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65  xing code omitte
1bf0: 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20  d due to the.** 
1c00: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1c10: 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  FE] compile-time
1c20: 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65   option being se
1c30: 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51  t to 0..**.** SQ
1c40: 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70  Lite can be comp
1c50: 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74  iled with or wit
1c60: 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57  hout mutexes.  W
1c70: 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  hen.** the [SQLI
1c80: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43  TE_THREADSAFE] C
1c90: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1ca0: 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d  cro is 1 or 2, m
1cb0: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
1cc0: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65  abled and SQLite
1cd0: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20   is threadsafe. 
1ce0: 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51   When the.** [SQ
1cf0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d00: 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a   macro is 0, .**
1d10: 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65   the mutexes are
1d20: 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f   omitted.  Witho
1d30: 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20  ut the mutexes, 
1d40: 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a  it is not safe.*
1d50: 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20  * to use SQLite 
1d60: 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f  concurrently fro
1d70: 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  m more than one 
1d80: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e  thread..**.** En
1d90: 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69  abling mutexes i
1da0: 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62  ncurs a measurab
1db0: 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70  le performance p
1dc0: 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66  enalty..** So if
1dd0: 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d   speed is of utm
1de0: 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20  ost importance, 
1df0: 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74  it makes sense t
1e00: 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  o disable.** the
1e10: 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66   mutexes.  But f
1e20: 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74  or maximum safet
1e30: 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  y, mutexes shoul
1e40: 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  d be enabled..**
1e50: 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 65   ^The default be
1e60: 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75  havior is for mu
1e70: 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62  texes to be enab
1e80: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  led..**.** This 
1e90: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
1ea0: 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c   used by an appl
1eb0: 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20  ication to make 
1ec0: 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
1ed0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69   version of SQLi
1ee0: 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69  te that it is li
1ef0: 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61  nking against wa
1f00: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
1f10: 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73  ** the desired s
1f20: 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53  etting of the [S
1f30: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1f40: 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54  ] macro..**.** T
1f50: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e  his interface on
1f60: 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68  ly reports on th
1f70: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  e compile-time m
1f80: 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20  utex setting.** 
1f90: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1fa0: 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e  HREADSAFE] flag.
1fb0: 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
1fc0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
1fd0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fe0: 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d  E=1 or =2 then m
1ff0: 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c  utexes are enabl
2000: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 75  ed by default bu
2010: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c  t.** can be full
2020: 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64  y or partially d
2030: 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20  isabled using a 
2040: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2050: 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69  _config()].** wi
2060: 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 51  th the verbs [SQ
2070: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
2080: 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49  LETHREAD], [SQLI
2090: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
20a0: 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  HREAD],.** or [S
20b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
20c0: 49 41 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65  IALIZED].  ^(The
20d0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
20e0: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
20f0: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
2100: 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79  ction shows only
2110: 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   the compile-tim
2120: 65 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20  e setting of.** 
2130: 74 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e  thread safety, n
2140: 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20  ot any run-time 
2150: 63 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20  changes to that 
2160: 73 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a  setting made by.
2170: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  ** sqlite3_confi
2180: 67 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  g(). In other wo
2190: 72 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20  rds, the return 
21a0: 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
21b0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a  e3_threadsafe().
21c0: 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20  ** is unchanged 
21d0: 62 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  by calls to sqli
21e0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a  te3_config().)^.
21f0: 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74  **.** See the [t
2200: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64  hreading mode] d
2210: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
2220: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
2230: 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20  rmation..*/.int 
2240: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2250: 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  fe(void);../*.**
2260: 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
2270: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48  ase Connection H
2280: 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44  andle.** KEYWORD
2290: 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  S: {database con
22a0: 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61  nection} {databa
22b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a  se connections}.
22c0: 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20  **.** Each open 
22d0: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
22e0: 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  is represented b
22f0: 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  y a pointer to a
2300: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a  n instance of.**
2310: 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75   the opaque stru
2320: 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c  cture named "sql
2330: 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73  ite3".  It is us
2340: 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66  eful to think of
2350: 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70   an sqlite3.** p
2360: 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a  ointer as an obj
2370: 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ect.  The [sqlit
2380: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
2390: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
23a0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
23b0: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
23c0: 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f  faces are its co
23d0: 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20  nstructors, and 
23e0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
23f0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2400: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72  3_close_v2()] ar
2410: 65 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72  e its destructor
2420: 73 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  s.  There are ma
2430: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65  ny other.** inte
2440: 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a  rfaces (such as.
2450: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2460: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
2470: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2480: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ion()], and.** [
2490: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
24a0: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20  eout()] to name 
24b0: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20  but three) that 
24c0: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61  are methods on a
24d0: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a  n.** sqlite3 obj
24e0: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
24f0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73  struct sqlite3 s
2500: 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43  qlite3;../*.** C
2510: 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20  API3REF: 64-Bit 
2520: 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a  Integer Types.**
2530: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
2540: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75  e_int64 sqlite_u
2550: 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61  int64.**.** Beca
2560: 75 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20  use there is no 
2570: 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77  cross-platform w
2580: 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34  ay to specify 64
2590: 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70  -bit integer typ
25a0: 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63  es.** SQLite inc
25b0: 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66  ludes typedefs f
25c0: 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  or 64-bit signed
25d0: 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e   and unsigned in
25e0: 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  tegers..**.** Th
25f0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
2600: 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  and sqlite3_uint
2610: 36 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65  64 are the prefe
2620: 72 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69  rred type defini
2630: 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71  tions..** The sq
2640: 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73  lite_int64 and s
2650: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70  qlite_uint64 typ
2660: 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  es are supported
2670: 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a   for backwards.*
2680: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
2690: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  only..**.** ^The
26a0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
26b0: 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  nd sqlite_int64 
26c0: 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20  types can store 
26d0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a  integer values.*
26e0: 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33  * between -92233
26f0: 37 32 30 33 36 38 35 34 37 37 35 38 30 38 20 61  72036854775808 a
2700: 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36 38 35  nd +922337203685
2710: 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76  4775807 inclusiv
2720: 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
2730: 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73  te3_uint64 and s
2740: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70  qlite_uint64 typ
2750: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2760: 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20  eger values .** 
2770: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31  between 0 and +1
2780: 38 34 34 36 37 34 34 30 37 33 37 30 39 35 35 31  8446744073709551
2790: 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a  615 inclusive..*
27a0: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
27b0: 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70  INT64_TYPE.  typ
27c0: 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  edef SQLITE_INT6
27d0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e  4_TYPE sqlite_in
27e0: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
27f0: 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49  nsigned SQLITE_I
2800: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
2810: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64  _uint64;.#elif d
2820: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2830: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
2840: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
2850: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
2860: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2870: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2880: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2890: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
28a0: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
28b0: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
28c0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
28d0: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
28e0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
28f0: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
2900: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2910: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2920: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2930: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
2940: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
2950: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2960: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2970: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2980: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
2990: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
29a0: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
29b0: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
29c0: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
29d0: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
29e0: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
29f0: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
2a00: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
2a10: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2a20: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  Connection.**.**
2a30: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2a40: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2a50: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2a60: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2a70: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2a80: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2a90: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2aa0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2ab0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2ac0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2ad0: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2ae0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2af0: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2b00: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2b10: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2b20: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2b30: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2b40: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2b50: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b60: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2b70: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2b80: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2b90: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ba0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2bb0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2bc0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2bd0: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2be0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2bf0: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2c00: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2c10: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2c20: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2c30: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2c40: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2c50: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2c60: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2c70: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2c80: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2c90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ca0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2cb0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2cc0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
2cd0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
2ce0: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
2cf0: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
2d00: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2d10: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
2d20: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
2d30: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
2d40: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
2d50: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
2d60: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
2d70: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
2d80: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
2d90: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
2da0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
2db0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
2dc0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
2dd0: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
2de0: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
2df0: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
2e00: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
2e10: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e20: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
2e30: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e40: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
2e50: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
2e60: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
2e70: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
2e80: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
2e90: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
2ea0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
2eb0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
2ec0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
2ed0: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
2ee0: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
2ef0: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
2f00: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
2f10: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
2f20: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
2f30: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
2f40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f50: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
2f60: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
2f70: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f80: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
2f90: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
2fa0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
2fb0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
2fc0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
2fd0: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
2fe0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
2ff0: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3000: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3010: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3020: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3030: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3040: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3050: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3060: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
3070: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
3080: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
3090: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
30a0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
30b0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
30c0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
30d0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
30e0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
30f0: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3100: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3110: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3120: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3130: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3140: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3150: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3160: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
3170: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3180: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
3190: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
31a0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
31b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
31c0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
31d0: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
31e0: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
31f0: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3200: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3210: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3220: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3230: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3240: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3250: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3260: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
3270: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
3280: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
3290: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
32a0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
32b0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
32c0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
32d0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
32e0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
32f0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3300: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3310: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3320: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3330: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3340: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3350: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3360: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
3370: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
3380: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65  erface.**.** The
3390: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
33a0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
33b0: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
33c0: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
33d0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
33e0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
33f0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
3400: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
3410: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
3420: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
3430: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
3440: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
3450: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
3460: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
3470: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
3480: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
3490: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
34a0: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
34b0: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
34c0: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
34d0: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
34e0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
34f0: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
3500: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
3510: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
3520: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3530: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
3540: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
3550: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
3560: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3570: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
3580: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
3590: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
35a0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
35b0: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
35c0: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
35d0: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
35e0: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
35f0: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
3600: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
3610: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3620: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
3630: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
3640: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
3650: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
3660: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
3670: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
3680: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
3690: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
36a0: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
36b0: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
36c0: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
36d0: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
36e0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
36f0: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
3700: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
3710: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3720: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
3730: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
3740: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
3750: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
3760: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
3770: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
3780: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
3790: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
37a0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
37b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
37c0: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
37d0: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
37e0: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
37f0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
3800: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3810: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
3820: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
3830: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
3840: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
3850: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
3860: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
3870: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
3880: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
3890: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
38a0: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
38b0: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
38c0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
38d0: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73  meter of.** of s
38e0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
38f0: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3900: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3910: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3920: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3930: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3940: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3950: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3960: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3970: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3980: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3990: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
39a0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
39b0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
39c0: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
39d0: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
39e0: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
39f0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3a00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3a10: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3a20: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3a30: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3a40: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3a50: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3a60: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3a70: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3a80: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3a90: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3aa0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3ab0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3ac0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3ad0: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3ae0: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3af0: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3b00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3b10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3b20: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3b30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3b40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3b50: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3b60: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3b70: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3b80: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3b90: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ba0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3bb0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3bc0: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3bd0: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3be0: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3bf0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3c00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3c10: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3c20: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3c30: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3c40: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3c50: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3c60: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3c70: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3c80: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3c90: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3ca0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3cb0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
3cc0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3cd0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
3ce0: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
3cf0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3d00: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3d10: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
3d20: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
3d30: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
3d40: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
3d50: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
3d60: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
3d70: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
3d80: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
3d90: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
3da0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
3db0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
3dc0: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
3dd0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
3de0: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
3df0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
3e00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3e10: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68  t insure that th
3e20: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
3e30: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3e40: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
3e50: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
3e60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3e70: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
3e80: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3e90: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
3ea0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3eb0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
3ec0: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
3ed0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
3ee0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
3ef0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
3f00: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
3f10: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3f20: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3f30: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
3f40: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
3f50: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
3f60: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
3f70: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
3f80: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
3f90: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
3fa0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
3fb0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
3fc0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
3fd0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
3fe0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ff0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4000: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4010: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4030: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4040: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4050: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
4060: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
4070: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
4080: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
4090: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40c0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
40d0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
40e0: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
40f0: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4110: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4120: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4130: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4140: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4150: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4160: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
4170: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
4180: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
4190: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
41a0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
41b0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
41c0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
41d0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
41e0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
41f0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4200: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4210: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4220: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4230: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4240: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4250: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
4260: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
4270: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
4280: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
4290: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
42a0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
42b0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
42c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
42d0: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
42e0: 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20  /* SQL error or 
42f0: 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65  missing database
4300: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4310: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4320: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4330: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4340: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4350: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4360: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
4370: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
4380: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4390: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
43a0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
43b0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
43c0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
43d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
43e0: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
43f0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4400: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4410: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4420: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4430: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4440: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4450: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4460: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
4470: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
4480: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
4490: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
44a0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
44b0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
44c0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
44d0: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
44e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
44f0: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4500: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4510: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4520: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4540: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4550: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4560: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
4570: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
4580: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
4590: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
45a0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
45b0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
45c0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
45d0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
45e0: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
45f0: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4600: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4610: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4620: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4630: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4640: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4650: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4660: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
4670: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
4680: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
4690: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
46a0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
46b0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
46c0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
46d0: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
46e0: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
46f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4700: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4710: 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d  * Database is em
4720: 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pty */.#define S
4730: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4740: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4750: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4760: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4770: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4780: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4790: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
47a0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
47b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47c0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
47d0: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
47e0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
47f0: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4800: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4810: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4820: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4830: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4840: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4850: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4860: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4870: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4880: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4890: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
48a0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
48b0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
48c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
48d0: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
48e0: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
48f0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4900: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4910: 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69      24   /* Auxi
4920: 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66  liary database f
4930: 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23  ormat error */.#
4940: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41  define SQLITE_RA
4950: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f  NGE       25   /
4960: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
4970: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20  to sqlite3_bind 
4980: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a  out of range */.
4990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
49a0: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20  OTADB      26   
49b0: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74  /* File opened t
49c0: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74  hat is not a dat
49d0: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
49e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
49f0: 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a  ICE      27   /*
4a00: 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66   Notifications f
4a10: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4a20: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4a30: 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20  ITE_WARNING     
4a40: 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73  28   /* Warnings
4a50: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f   from sqlite3_lo
4a60: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  g() */.#define S
4a70: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4a80: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4a90: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4aa0: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4ab0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4ac0: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4ad0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4ae0: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4af0: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4b00: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4b10: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4b20: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4b30: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4b40: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4b50: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4b60: 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a   definitions}.**
4b70: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
4b80: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
4b90: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
4ba0: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
4bb0: 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a   of 30 integer.*
4bc0: 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  * [result codes]
4bd0: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4be0: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4bf0: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
4c00: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4c10: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
4c20: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
4c30: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
4c40: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
4c50: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
4c60: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
4c70: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
4c80: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4c90: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4ca0: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4cb0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4cc0: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20  rsion 3.3.8 and 
4cd0: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a  later) include.*
4ce0: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64  * support for ad
4cf0: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20  ditional result 
4d00: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69  codes that provi
4d10: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  de more detailed
4d20: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
4d30: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68  about errors. Th
4d40: 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65  ese [extended re
4d50: 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20  sult codes] are 
4d60: 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
4d70: 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20  led.** on a per 
4d80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4d90: 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20  ion basis using 
4da0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
4db0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
4dc0: 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f  codes()] API.  O
4dd0: 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20  r, the extended 
4de0: 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  code for.** the 
4df0: 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f  most recent erro
4e00: 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  r can be obtaine
4e10: 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
4e20: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
4e30: 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  code()]..*/.#def
4e40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4e50: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
4e60: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4e70: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
4e80: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4e90: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20  SHORT_READ      
4ea0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4eb0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
4ec0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57  e SQLITE_IOERR_W
4ed0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
4ee0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4ef0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
4f00: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
4f10: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
4f20: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f30: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
4f40: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
4f50: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28  _FSYNC         (
4f60: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4f70: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
4f80: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e  QLITE_IOERR_TRUN
4f90: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53  CATE          (S
4fa0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36  QLITE_IOERR | (6
4fb0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4fc0: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54  LITE_IOERR_FSTAT
4fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4fe0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c  LITE_IOERR | (7<
4ff0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5000: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b  ITE_IOERR_UNLOCK
5010: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5020: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c  ITE_IOERR | (8<<
5030: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5040: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20  TE_IOERR_RDLOCK 
5050: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5060: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38  TE_IOERR | (9<<8
5070: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5080: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20  E_IOERR_DELETE  
5090: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38  E_IOERR | (10<<8
50b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50c0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20  E_IOERR_BLOCKED 
50d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38  E_IOERR | (11<<8
50f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5100: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20  E_IOERR_NOMEM   
5110: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5120: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38  E_IOERR | (12<<8
5130: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5140: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20  E_IOERR_ACCESS  
5150: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5160: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38  E_IOERR | (13<<8
5170: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5180: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53  E_IOERR_CHECKRES
5190: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54  ERVEDLOCK (SQLIT
51a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38  E_IOERR | (14<<8
51b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
51c0: 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20  E_IOERR_LOCK    
51d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
51e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38  E_IOERR | (15<<8
51f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5200: 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20  E_IOERR_CLOSE   
5210: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5220: 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38  E_IOERR | (16<<8
5230: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5240: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53  E_IOERR_DIR_CLOS
5250: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  E         (SQLIT
5260: 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38  E_IOERR | (17<<8
5270: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5280: 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20  E_IOERR_SHMOPEN 
5290: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
52a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38  E_IOERR | (18<<8
52b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
52c0: 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20  E_IOERR_SHMSIZE 
52d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
52e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38  E_IOERR | (19<<8
52f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5300: 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20  E_IOERR_SHMLOCK 
5310: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5320: 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38  E_IOERR | (20<<8
5330: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5340: 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20  E_IOERR_SHMMAP  
5350: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5360: 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38  E_IOERR | (21<<8
5370: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5380: 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20  E_IOERR_SEEK    
5390: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
53a0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38  E_IOERR | (22<<8
53b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
53c0: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e  E_IOERR_DELETE_N
53d0: 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54  OENT      (SQLIT
53e0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38  E_IOERR | (23<<8
53f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5400: 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20  E_IOERR_MMAP    
5410: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5420: 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38  E_IOERR | (24<<8
5430: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5440: 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50  E_IOERR_GETTEMPP
5450: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5460: 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38  E_IOERR | (25<<8
5470: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5480: 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48  E_IOERR_CONVPATH
5490: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
54a0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38  E_IOERR | (26<<8
54b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
54c0: 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43  E_LOCKED_SHAREDC
54d0: 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54  ACHE      (SQLIT
54e0: 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c  E_LOCKED |  (1<<
54f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5500: 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59  TE_BUSY_RECOVERY
5510: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5520: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c  TE_BUSY   |  (1<
5530: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5540: 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f  ITE_BUSY_SNAPSHO
5550: 54 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  T           (SQL
5560: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32  ITE_BUSY   |  (2
5570: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5580: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
5590: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
55a0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
55b0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
55c0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
55d0: 49 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28  ISDIR          (
55e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
55f0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5600: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5610: 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20  N_FULLPATH      
5620: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5630: 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  N | (3<<8)).#def
5640: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5650: 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20  PEN_CONVPATH    
5660: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
5670: 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  PEN | (4<<8)).#d
5680: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
5690: 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20  RUPT_VTAB       
56a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52       (SQLITE_COR
56b0: 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23  RUPT | (1<<8)).#
56c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
56d0: 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20  ADONLY_RECOVERY 
56e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
56f0: 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29  ADONLY | (1<<8))
5700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5710: 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43  READONLY_CANTLOC
5720: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  K       (SQLITE_
5730: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38  READONLY | (2<<8
5740: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5750: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42  E_READONLY_ROLLB
5760: 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  ACK       (SQLIT
5770: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c  E_READONLY | (3<
5780: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5790: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d  ITE_READONLY_DBM
57a0: 4f 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c  OVED        (SQL
57b0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
57c0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
57d0: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
57e0: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
57f0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
5800: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5810: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5820: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
5830: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5840: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5850: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5860: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
5870: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5880: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
5890: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
58a0: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
58b0: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
58c0: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
58d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
58e0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
58f0: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5900: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5910: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5920: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5930: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
5940: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5950: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
5960: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5970: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
5980: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5990: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
59a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
59b0: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
59c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
59d0: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
59e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
59f0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
5a00: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
5a10: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
5a20: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5a30: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5a40: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
5a50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5a60: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
5a70: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5a80: 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20  INT_ROWID       
5a90: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5aa0: 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64  INT |(10<<8)).#d
5ab0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
5ac0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20  ICE_RECOVER_WAL 
5ad0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54       (SQLITE_NOT
5ae0: 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ICE | (1<<8)).#d
5af0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
5b00: 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c  ICE_RECOVER_ROLL
5b10: 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54  BACK (SQLITE_NOT
5b20: 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ICE | (2<<8)).#d
5b30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
5b40: 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20  NING_AUTOINDEX  
5b50: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52       (SQLITE_WAR
5b60: 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23  NING | (1<<8)).#
5b70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
5b80: 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20  TH_USER         
5b90: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55        (SQLITE_AU
5ba0: 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a  TH | (1<<8))../*
5bb0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
5bc0: 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65  ags For File Ope
5bd0: 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a  n Operations.**.
5be0: 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c  ** These bit val
5bf0: 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  ues are intended
5c00: 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a   for use in the.
5c10: 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ** 3rd parameter
5c20: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5c30: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
5c40: 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20  rface and.** in 
5c50: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
5c60: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
5c70: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
5c80: 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  hod..*/.#define 
5c90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
5ca0: 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30  ONLY         0x0
5cb0: 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66  0000001  /* Ok f
5cc0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5cd0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5ce0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
5cf0: 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30  WRITE        0x0
5d00: 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66  0000002  /* Ok f
5d10: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5d20: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5d30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
5d40: 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30  TE           0x0
5d50: 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66  0000004  /* Ok f
5d60: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5d70: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5d80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
5d90: 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30  TEONCLOSE    0x0
5da0: 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20  0000008  /* VFS 
5db0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5dc0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
5dd0: 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30  USIVE        0x0
5de0: 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20  0000010  /* VFS 
5df0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5e00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f  SQLITE_OPEN_AUTO
5e10: 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30  PROXY        0x0
5e20: 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20  0000020  /* VFS 
5e30: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5e40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
5e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5e60: 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66  0000040  /* Ok f
5e70: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5e80: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5e90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f  SQLITE_OPEN_MEMO
5ea0: 52 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30  RY           0x0
5eb0: 30 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66  0000080  /* Ok f
5ec0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5ed0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5ee0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
5ef0: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
5f00: 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20  0000100  /* VFS 
5f10: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5f20: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
5f30: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
5f40: 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20  0000200  /* VFS 
5f50: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5f60: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
5f70: 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30  SIENT_DB     0x0
5f80: 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20  0000400  /* VFS 
5f90: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5fa0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
5fb0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
5fc0: 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20  0000800  /* VFS 
5fd0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5fe0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
5ff0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
6000: 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20  0001000  /* VFS 
6010: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
6020: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
6030: 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30  OURNAL       0x0
6040: 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20  0002000  /* VFS 
6050: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
6060: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
6070: 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30  ER_JOURNAL   0x0
6080: 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20  0004000  /* VFS 
6090: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
60a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
60b0: 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30  TEX          0x0
60c0: 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0008000  /* Ok f
60d0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
60e0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
60f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
6100: 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30  MUTEX        0x0
6110: 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0010000  /* Ok f
6120: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
6130: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
6140: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
6150: 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30  EDCACHE      0x0
6160: 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0020000  /* Ok f
6170: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
6180: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
6190: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
61a0: 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30  ATECACHE     0x0
61b0: 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0040000  /* Ok f
61c0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
61d0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
61e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20  SQLITE_OPEN_WAL 
61f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6200: 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20  0080000  /* VFS 
6210: 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65  only */../* Rese
6220: 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20  rved:           
6230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6240: 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a  00F00000 */../*.
6250: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76  ** CAPI3REF: Dev
6260: 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74  ice Characterist
6270: 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44  ics.**.** The xD
6280: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
6290: 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  tics method of t
62a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
62b0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63  ethods].** objec
62c0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  t returns an int
62d0: 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20  eger which is a 
62e0: 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a  vector of these.
62f0: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
6300: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
6310: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
6320: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
6330: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
6340: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
6350: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
6360: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
6370: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
6380: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6390: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
63a0: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
63b0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
63c0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
63d0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
63e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
63f0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6400: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
6410: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
6420: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
6430: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
6440: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
6450: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
6460: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
6470: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
6480: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6490: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
64a0: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
64b0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
64c0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
64d0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
64e0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
64f0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
6500: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
6510: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
6520: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
6530: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
6540: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6550: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
6560: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
6570: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
6580: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
6590: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
65a0: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
65b0: 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c  rite().  The SQL
65c0: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
65d0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72  AFE_OVERWRITE pr
65e0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
65f0: 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f  t.** after reboo
6600: 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72  t following a cr
6610: 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73  ash or power los
6620: 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65  s, the only byte
6630: 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74  s in a.** file t
6640: 68 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e  hat were written
6650: 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74   at the applicat
6660: 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20  ion level might 
6670: 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  have changed.** 
6680: 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e  and that adjacen
6690: 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79  t bytes, even by
66a0: 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73  tes within the s
66b0: 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a  ame sector are.*
66c0: 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  * guaranteed to 
66d0: 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54  be unchanged.  T
66e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
66f0: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
6700: 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e  _OPEN.** flag in
6710: 64 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69  dicate that a fi
6720: 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c  le cannot be del
6730: 65 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20  eted when open. 
6740: 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49   The.** SQLITE_I
6750: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66  OCAP_IMMUTABLE f
6760: 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68  lag indicates th
6770: 61 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f  at the file is o
6780: 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  n.** read-only m
6790: 65 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20  edia and cannot 
67a0: 62 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20  be changed even 
67b0: 62 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74  by processes wit
67c0: 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72  h.** elevated pr
67d0: 69 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65  ivileges..*/.#de
67e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
67f0: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
6800: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6810: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
6820: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
6830: 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20  12              
6840: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
6850: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6860: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
6870: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6880: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
6890: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20  _IOCAP_ATOMIC2K 
68a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
68b0: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
68c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
68d0: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20  OMIC4K          
68e0: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
68f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6900: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
6910: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6920: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
6930: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6940: 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20  IC16K           
6950: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64     0x00000040.#d
6960: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6970: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20  AP_ATOMIC32K    
6980: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6990: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0080.#define SQL
69a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
69b0: 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  64K             
69c0: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
69d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
69e0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
69f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
6a00: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6a10: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6a20: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30  AL             0
6a30: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e  x00000400.#defin
6a40: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
6a50: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6a60: 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30  OPEN  0x00000800
6a70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6a80: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6a90: 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30  OVERWRITE    0x0
6aa0: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20  0001000.#define 
6ab0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
6ac0: 55 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  UTABLE          
6ad0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a      0x00002000..
6ae0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6af0: 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76  File Locking Lev
6b00: 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  els.**.** SQLite
6b10: 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65   uses one of the
6b20: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
6b30: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  s as the second.
6b40: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  ** argument to c
6b50: 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f  alls it makes to
6b60: 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64   the xLock() and
6b70: 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f   xUnlock() metho
6b80: 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c  ds.** of an [sql
6b90: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6ba0: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66   object..*/.#def
6bb0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6bc0: 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a  NONE          0.
6bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6be0: 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20  OCK_SHARED      
6bf0: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
6c00: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
6c10: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
6c20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
6c30: 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66  ING       3.#def
6c40: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6c50: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a  EXCLUSIVE     4.
6c60: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6c70: 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   Synchronization
6c80: 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a   Type Flags.**.*
6c90: 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  * When SQLite in
6ca0: 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28  vokes the xSync(
6cb0: 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a  ) method of an.*
6cc0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
6cd0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74  thods] object it
6ce0: 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74   uses a combinat
6cf0: 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  ion of.** these 
6d00: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
6d10: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
6d20: 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ument..**.** Whe
6d30: 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  n the SQLITE_SYN
6d40: 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20  C_DATAONLY flag 
6d50: 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e  is used, it mean
6d60: 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79  s that the.** sy
6d70: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c  nc operation onl
6d80: 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68  y needs to flush
6d90: 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74   data to mass st
6da0: 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a  orage.  Inode.**
6db0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65   information nee
6dc0: 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64  d not be flushed
6dd0: 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  . If the lower f
6de0: 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20  our bits of the 
6df0: 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51  flag.** equal SQ
6e00: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
6e10: 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20  , that means to 
6e20: 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  use normal fsync
6e30: 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a  () semantics..**
6e40: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
6e50: 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51  ur bits equal SQ
6e60: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
6e70: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f  that means.** to
6e80: 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74   use Mac OS X st
6e90: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73  yle fullsync ins
6ea0: 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e  tead of fsync().
6eb0: 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f  .**.** Do not co
6ec0: 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45  nfuse the SQLITE
6ed0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6ee0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6ef0: 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20  L flags.** with 
6f00: 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  the [PRAGMA sync
6f10: 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20  hronous]=NORMAL 
6f20: 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  and [PRAGMA sync
6f30: 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a  hronous]=FULL.**
6f40: 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20   settings.  The 
6f50: 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61  [synchronous pra
6f60: 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20  gma] determines 
6f70: 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68  when calls to th
6f80: 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d  e.** xSync VFS m
6f90: 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20  ethod occur and 
6fa0: 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c  applies uniforml
6fb0: 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61  y across all pla
6fc0: 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53  tforms..** The S
6fd0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6fe0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
6ff0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74  C_FULL flags det
7000: 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e  ermine how.** en
7010: 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72  ergetic or rigor
7020: 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20  ous or forceful 
7030: 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69  the sync operati
7040: 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f  ons are and.** o
7050: 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65  nly make a diffe
7060: 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58  rence on Mac OSX
7070: 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74   for the default
7080: 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a   SQLite code..**
7090: 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46   (Third-party VF
70a0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
70b0: 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b  s might also mak
70c0: 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
70d0: 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c  n.** between SQL
70e0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
70f0: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
7100: 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20  FULL, but among 
7110: 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67  the.** operating
7120: 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c   systems nativel
7130: 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  y supported by S
7140: 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20  QLite, only Mac 
7150: 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f  OSX.** cares abo
7160: 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63  ut the differenc
7170: 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e.).*/.#define S
7180: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
7190: 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32  L        0x00002
71a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
71b0: 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20  SYNC_FULL       
71c0: 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69     0x00003.#defi
71d0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  ne SQLITE_SYNC_D
71e0: 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30  ATAONLY      0x0
71f0: 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0010../*.** CAPI
7200: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
7210: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e  ce Open File Han
7220: 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71  dle.**.** An [sq
7230: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7240: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
7250: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68   open file in th
7260: 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  e .** [sqlite3_v
7270: 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63  fs | OS interfac
7280: 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76  e layer].  Indiv
7290: 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61  idual OS interfa
72a0: 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ce.** implementa
72b0: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61  tions will.** wa
72c0: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74  nt to subclass t
72d0: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70  his object by ap
72e0: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e  pending addition
72f0: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72  al fields.** for
7300: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20   their own use. 
7310: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e   The pMethods en
7320: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72  try is a pointer
7330: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
7340: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
7350: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
7360: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70  es methods for p
7370: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f  erforming.** I/O
7380: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
7390: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f  he open file..*/
73a0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
73b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c  sqlite3_file sql
73c0: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63  ite3_file;.struc
73d0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b  t sqlite3_file {
73e0: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20  .  const struct 
73f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7400: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f  ds *pMethods;  /
7410: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e  * Methods for an
7420: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b   open file */.};
7430: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7440: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46  : OS Interface F
7450: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68  ile Virtual Meth
7460: 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ods Object.**.**
7470: 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e   Every file open
7480: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
7490: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
74a0: 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61  thod populates a
74b0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  n.** [sqlite3_fi
74c0: 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20  le] object (or, 
74d0: 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61  more commonly, a
74e0: 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
74f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7500: 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20  e] object) with 
7510: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
7520: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
7530: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73   object..** This
7540: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
7550: 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64  the methods used
7560: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
7570: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ous operations.*
7580: 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70  * against the op
7590: 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e  en file represen
75a0: 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ted by the [sqli
75b0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
75c0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ..**.** If the [
75d0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
75e0: 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74  n] method sets t
75f0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
7600: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
7610: 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55   .** to a non-NU
7620: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
7630: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f   the sqlite3_io_
7640: 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d  methods.xClose m
7650: 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20  ethod.** may be 
7660: 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20  invoked even if 
7670: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7680: 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64  .xOpen] reported
7690: 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e   that it failed.
76a0: 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61    The.** only wa
76b0: 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63  y to prevent a c
76c0: 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f  all to xClose fo
76d0: 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64  llowing a failed
76e0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
76f0: 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74  pen].** is for t
7700: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7710: 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68  xOpen] to set th
7720: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
7730: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a  Methods element.
7740: 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ** to NULL..**.*
7750: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
7760: 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61  ment to xSync ma
7770: 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  y be one of [SQL
7780: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d  ITE_SYNC_NORMAL]
7790: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53   or.** [SQLITE_S
77a0: 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20  YNC_FULL].  The 
77b0: 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20  first choice is 
77c0: 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  the normal fsync
77d0: 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ()..** The secon
77e0: 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61  d choice is a Ma
77f0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
7800: 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c  lsync.  The [SQL
7810: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7820: 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62  Y].** flag may b
7830: 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64  e ORed in to ind
7840: 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20  icate that only 
7850: 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20  the data of the 
7860: 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20  file.** and not 
7870: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20  its inode needs 
7880: 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a  to be synced..**
7890: 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20  .** The integer 
78a0: 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28  values to xLock(
78b0: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
78c0: 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75  are one of.** <u
78d0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
78e0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a  TE_LOCK_NONE],.*
78f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7900: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
7910: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7920: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20  K_RESERVED],.** 
7930: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7940: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a  K_PENDING], or.*
7950: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7960: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a  OCK_EXCLUSIVE]..
7970: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63  ** </ul>.** xLoc
7980: 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68  k() increases th
7990: 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28  e lock. xUnlock(
79a0: 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20  ) decreases the 
79b0: 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68  lock..** The xCh
79c0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28  eckReservedLock(
79d0: 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20  ) method checks 
79e0: 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61  whether any data
79f0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
7a00: 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68  .** either in th
7a10: 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e  is process or in
7a20: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63   some other proc
7a30: 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20  ess, is holding 
7a40: 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50  a RESERVED,.** P
7a50: 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55  ENDING, or EXCLU
7a60: 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  SIVE lock on the
7a70: 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72   file.  It retur
7a80: 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75  ns true.** if su
7a90: 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73  ch a lock exists
7aa0: 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72   and false other
7ab0: 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  wise..**.** The 
7ac0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
7ad0: 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72  ethod is a gener
7ae0: 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ic interface tha
7af0: 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a  t allows custom.
7b00: 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ** VFS implement
7b10: 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74  ations to direct
7b20: 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70  ly control an op
7b30: 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68  en file using th
7b40: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
7b50: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  le_control()] in
7b60: 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65  terface.  The se
7b70: 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65  cond "op" argume
7b80: 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65  nt is an.** inte
7b90: 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65  ger opcode.  The
7ba0: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
7bb0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69  is a generic poi
7bc0: 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f  nter intended to
7bd0: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  .** point to a s
7be0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61  tructure that ma
7bf0: 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65  y contain argume
7c00: 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20  nts or space in 
7c10: 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74  which to.** writ
7c20: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e  e return values.
7c30: 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73    Potential uses
7c40: 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f   for xFileContro
7c50: 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20  l() might be.** 
7c60: 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61  functions to ena
7c70: 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63  ble blocking loc
7c80: 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73  ks with timeouts
7c90: 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a  , to change the.
7ca0: 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74  ** locking strat
7cb0: 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  egy (for example
7cc0: 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65   to use dot-file
7cd0: 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75   locks), to inqu
7ce0: 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65  ire.** about the
7cf0: 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63   status of a loc
7d00: 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73  k, or to break s
7d10: 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65  tale locks.  The
7d20: 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20   SQLite.** core 
7d30: 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63  reserves all opc
7d40: 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31  odes less than 1
7d50: 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75  00 for its own u
7d60: 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63  se..** A [file c
7d70: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c  ontrol opcodes |
7d80: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
7d90: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
7da0: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
7db0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
7dc0: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
7dd0: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
7de0: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
7df0: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
7e00: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
7e10: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
7e20: 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  .  VFS implement
7e30: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a  ations should.**
7e40: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
7e50: 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69  NOTFOUND] for fi
7e60: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
7e70: 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  es that they do 
7e80: 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65  not.** recognize
7e90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
7ea0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
7eb0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
7ec0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
7ed0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
7ee0: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
7ef0: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
7f00: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
7f10: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
7f20: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
7f30: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
7f40: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
7f50: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
7f60: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
7f70: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
7f80: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
7f90: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
7fa0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
7fb0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
7fc0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
7fd0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
7fe0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7ff0: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
8000: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8010: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
8020: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8030: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
8040: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8050: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
8060: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8070: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
8080: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8090: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
80a0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
80b0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
80c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
80d0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
80e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
80f0: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
8100: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8110: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
8120: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8130: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
8140: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
8150: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8160: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
8170: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
8180: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
8190: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
81a0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
81b0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
81c0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
81d0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
81e0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
81f0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
8200: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
8210: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
8220: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
8230: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
8240: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
8250: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
8260: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
8270: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
8280: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
8290: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
82a0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
82b0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
82c0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
82d0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
82e0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
82f0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
8300: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
8310: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
8320: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
8330: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
8340: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
8350: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
8360: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
8370: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
8380: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
8390: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
83a0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
83b0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
83c0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
83d0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
83e0: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
83f0: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
8400: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
8410: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
8420: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
8430: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
8440: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
8450: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
8460: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
8470: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
8480: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
8490: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
84a0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
84b0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
84c0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
84d0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
84e0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
84f0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
8500: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
8510: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
8520: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
8530: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
8540: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
8550: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
8560: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8570: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
8580: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
8590: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
85a0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
85b0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
85c0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
85d0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
85e0: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
85f0: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
8600: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
8610: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
8620: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
8630: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8640: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
8650: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
8660: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8670: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
8680: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8690: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
86a0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
86b0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
86c0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
86d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
86e0: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
86f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
8700: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
8710: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
8720: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8730: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
8740: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
8750: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8760: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8770: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8780: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
8790: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
87a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
87b0: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
87c0: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
87d0: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
87e0: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
87f0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
8800: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
8810: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
8820: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
8830: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8840: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
8850: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8860: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
8870: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
8880: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8890: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
88a0: 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29  .  int (*xFetch)
88b0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
88c0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
88d0: 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76  fst, int iAmt, v
88e0: 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74  oid **pp);.  int
88f0: 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c   (*xUnfetch)(sql
8900: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8910: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
8920: 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20   void *p);.  /* 
8930: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8940: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8950: 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64  ion 3 */.  /* Ad
8960: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
8970: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
8980: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
8990: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
89a0: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
89b0: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
89c0: 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  codes.** KEYWORD
89d0: 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  S: {file control
89e0: 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20   opcodes} {file 
89f0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a  control opcode}.
8a00: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
8a10: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
8a20: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
8a30: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
8a40: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
8a50: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
8a60: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
8a70: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
8a80: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
8a90: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  .** interface..*
8aa0: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
8ab0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
8ac0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8ad0: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
8ae0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
8af0: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
8b00: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
8b10: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
8b20: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
8b30: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
8b40: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
8b50: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
8b60: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
8b70: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
8b80: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
8b90: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
8ba0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
8bb0: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
8bc0: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
8bd0: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
8be0: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
8bf0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
8c00: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
8c10: 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79  testing and only
8c20: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
8c30: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
8c40: 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65  TE_TEST.** is de
8c50: 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a  fined..** <ul>.*
8c60: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8c70: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
8c80: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8c90: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8ca0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8cb0: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
8cc0: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
8cd0: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
8ce0: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
8cf0: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
8d00: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
8d10: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
8d20: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
8d30: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
8d40: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
8d50: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
8d60: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
8d70: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
8d80: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
8d90: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
8da0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
8db0: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
8dc0: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
8dd0: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
8de0: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
8df0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
8e00: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
8e10: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8e20: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
8e30: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8e40: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
8e50: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
8e60: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
8e70: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
8e80: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
8e90: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8ea0: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
8eb0: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
8ec0: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
8ed0: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
8ee0: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
8ef0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
8f00: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
8f10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
8f20: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
8f30: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
8f40: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
8f50: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
8f60: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
8f70: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
8f80: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
8f90: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
8fa0: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
8fb0: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
8fc0: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
8fd0: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
8fe0: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
8ff0: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
9000: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
9010: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
9020: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
9030: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9040: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
9050: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9060: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
9070: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9080: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9090: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
90a0: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
90b0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
90c0: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65  ection.  See the
90d0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
90e0: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65  ontrol()] docume
90f0: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61  ntation for.** a
9100: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
9110: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
9120: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9130: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a  SYNC_OMITTED]].*
9140: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75  * No longer in u
9150: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  se..**.** <li>[[
9160: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9170: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  C]].** The [SQLI
9180: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f  TE_FCNTL_SYNC] o
9190: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
91a0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
91b0: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73   SQLite and.** s
91c0: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69  ent to the VFS i
91d0: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
91e0: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  e the xSync meth
91f0: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  od is invoked on
9200: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66   a.** database f
9210: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20  ile descriptor. 
9220: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63  Or, if the xSync
9230: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69   method is not i
9240: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75  nvoked .** becau
9250: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20  se the user has 
9260: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74  configured SQLit
9270: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47  e with .** [PRAG
9280: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
9290: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
92a0: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69  ous=OFF] it is i
92b0: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20  nvoked in place 
92c0: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63  .** of the xSync
92d0: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74   method. In most
92e0: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e   cases, the poin
92f0: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ter argument pas
9300: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73  sed with.** this
9310: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
9320: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20   NULL. However, 
9330: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
9340: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79  file is being sy
9350: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20  nced.** as part 
9360: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62  of a multi-datab
9370: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20  ase commit, the 
9380: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
9390: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  to a nul-termina
93a0: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  ted.** string co
93b0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61  ntaining the tra
93c0: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72  nsactions master
93d0: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61  -journal file na
93e0: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a  me. VFSes that .
93f0: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ** do not need t
9400: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c  his signal shoul
9410: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
9420: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
9430: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20  pplications .** 
9440: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
9450: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9460: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
9470: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
9480: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69  ng so may .** di
9490: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
94a0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
94b0: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
94c0: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
94d0: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
94e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
94f0: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a  IT_PHASETWO]].**
9500: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9510: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
9520: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  WO] opcode is ge
9530: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
9540: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ly by SQLite.** 
9550: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20  and sent to the 
9560: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e  VFS after a tran
9570: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e  saction has been
9580: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64   committed immed
9590: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65  iately.** but be
95a0: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73  fore the databas
95b0: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56  e is unlocked. V
95c0: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  FSes that do not
95d0: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
95e0: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65  l.** should sile
95f0: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
9600: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
9610: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
9620: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
9630: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9640: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
9650: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
9660: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a  ay disrupt the .
9670: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  ** operation of 
9680: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
9690: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
96a0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
96b0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
96c0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
96d0: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
96e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
96f0: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
9700: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
9710: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
9720: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
9730: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
9740: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
9750: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
9760: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
9770: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
9780: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
9790: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
97a0: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
97b0: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
97c0: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
97d0: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
97e0: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
97f0: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
9800: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
9810: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
9820: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
9830: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
9840: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
9850: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
9860: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
9870: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
9880: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
9890: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
98a0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
98b0: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
98c0: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
98d0: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
98e0: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
98f0: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
9900: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9910: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
9920: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
9930: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
9940: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
9950: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9960: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
9970: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
9980: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
9990: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
99a0: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
99b0: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
99c0: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
99d0: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
99e0: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
99f0: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
9a00: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
9a10: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
9a20: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
9a30: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
9a40: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
9a50: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
9a60: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
9a70: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
9a80: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
9a90: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
9aa0: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
9ab0: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
9ac0: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
9ad0: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
9ae0: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
9af0: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
9b00: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9b10: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9b20: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
9b30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
9b40: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
9b50: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9b60: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9b70: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
9b80: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
9b90: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
9ba0: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
9bb0: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
9bc0: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
9bd0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9be0: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
9bf0: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
9c00: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
9c10: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
9c20: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
9c30: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
9c40: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
9c50: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
9c60: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
9c70: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
9c80: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
9c90: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
9ca0: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
9cb0: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
9cc0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
9cd0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
9ce0: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
9cf0: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
9d00: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
9d10: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
9d20: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
9d30: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
9d40: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
9d50: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
9d60: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
9d70: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
9d80: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
9d90: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
9da0: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
9db0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
9dc0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9dd0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
9de0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
9df0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9e00: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
9e10: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
9e20: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
9e30: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
9e40: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
9e50: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
9e60: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
9e70: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
9e80: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
9e90: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
9ea0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
9eb0: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
9ec0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9ed0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
9ee0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
9ef0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9f00: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
9f10: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
9f20: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9f30: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9f40: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
9f50: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
9f60: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
9f70: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
9f80: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
9f90: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
9fa0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
9fb0: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
9fc0: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
9fd0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
9fe0: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
9ff0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a000: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a010: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a020: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a030: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a040: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a050: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a060: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a070: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a080: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a090: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
a0a0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a0b0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a0c0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a0d0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a0e0: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
a0f0: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
a100: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a110: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a120: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a130: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a140: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a150: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a160: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
a170: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
a180: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
a190: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
a1a0: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
a1b0: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
a1c0: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
a1d0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a1e0: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
a1f0: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
a200: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
a210: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
a220: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
a230: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
a240: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a250: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
a260: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a270: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
a280: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
a290: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
a2a0: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
a2b0: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
a2c0: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
a2d0: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
a2e0: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
a2f0: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
a300: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
a310: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
a320: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
a330: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a340: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
a350: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
a360: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a370: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
a380: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
a390: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
a3a0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
a3b0: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
a3c0: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
a3d0: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
a3e0: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
a3f0: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
a400: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
a410: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
a420: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
a430: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
a440: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
a450: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
a460: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
a470: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
a480: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
a490: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
a4a0: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
a4b0: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
a4c0: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
a4d0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
a4e0: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
a4f0: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
a500: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
a510: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a520: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
a530: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
a540: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
a550: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
a560: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
a570: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
a580: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
a590: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
a5a0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
a5b0: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
a5c0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
a5d0: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
a5e0: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
a5f0: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
a600: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
a610: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a620: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
a630: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
a640: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
a650: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
a660: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
a670: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
a680: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
a690: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
a6a0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
a6b0: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
a6c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
a6d0: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
a6e0: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
a6f0: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
a700: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
a710: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
a720: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a730: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
a740: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
a750: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
a760: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
a770: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
a780: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
a790: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
a7a0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
a7b0: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
a7c0: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
a7d0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
a7e0: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
a7f0: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
a800: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
a810: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
a820: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
a830: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a840: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a850: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
a860: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a870: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
a880: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
a890: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
a8a0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
a8b0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
a8c0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
a8d0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
a8e0: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
a8f0: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
a900: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
a910: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
a920: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
a930: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
a940: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
a950: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
a960: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
a970: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a980: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
a990: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73  turns.** any res
a9a0: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74  ult code other t
a9b0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  han [SQLITE_OK] 
a9c0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  or [SQLITE_NOTFO
a9d0: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  UND], that means
a9e0: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53  .** that the VFS
a9f0: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20   encountered an 
aa00: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64  error while hand
aa10: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  ling the [PRAGMA
aa20: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  ] and the.** com
aa30: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  pilation of the 
aa40: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74  PRAGMA fails wit
aa50: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68  h an error.  ^Th
aa60: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
aa70: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
aa80: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61  control occurs a
aa90: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  t the beginning 
aaa0: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  of pragma statem
aab0: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64  ent analysis and
aac0: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c   so.** it is abl
aad0: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75  e to override bu
aae0: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20  ilt-in [PRAGMA] 
aaf0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
ab00: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ab10: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
ab20: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
ab30: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
ab40: 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f  DLER].** file-co
ab50: 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76  ntrol may be inv
ab60: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f  oked by SQLite o
ab70: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
ab80: 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68  ile handle.** sh
ab90: 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69  ortly after it i
aba0: 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65  s opened in orde
abb0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63  r to provide a c
abc0: 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61  ustom VFS with a
abd0: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20  ccess.** to the 
abe0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79  connections busy
abf0: 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
ac00: 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  k. The argument 
ac10: 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  is of type (void
ac20: 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72   **).** - an arr
ac30: 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20  ay of two (void 
ac40: 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66  *) values. The f
ac50: 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63  irst (void *) ac
ac60: 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a  tually points.**
ac70: 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
ac80: 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28  f type (int (*)(
ac90: 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64  void *)). In ord
aca0: 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  er to invoke the
acb0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
acc0: 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68  busy-handler, th
acd0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  is function shou
ace0: 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ld be invoked wi
acf0: 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76  th the second (v
ad00: 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65  oid *) in.** the
ad10: 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e   array as the on
ad20: 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20  ly argument. If 
ad30: 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  it returns non-z
ad40: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70  ero, then the op
ad50: 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  eration.** shoul
ad60: 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66  d be retried. If
ad70: 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f   it returns zero
ad80: 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53  , the custom VFS
ad90: 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20   should abandon 
ada0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f  the.** current o
adb0: 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  peration..**.** 
adc0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
add0: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
ade0: 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f  ].** ^Applicatio
adf0: 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65  n can invoke the
ae00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
ae10: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c  EMPFILENAME] fil
ae20: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20  e-control.** to 
ae30: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65  have SQLite gene
ae40: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72  rate a.** tempor
ae50: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69  ary filename usi
ae60: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
ae70: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f  rithm that is fo
ae80: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61  llowed to genera
ae90: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
aea0: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45  filenames for TE
aeb0: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74  MP tables and ot
aec0: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65  her internal use
aed0: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d  s.  The.** argum
aee0: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ent should be a 
aef0: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c  char** which wil
af00: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68  l be filled with
af10: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
af20: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
af30: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
af40: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
af50: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c  oc()].  The call
af60: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76  er should.** inv
af70: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
af80: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75  e()] on the resu
af90: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65  lt to avoid a me
afa0: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a  mory leak..**.**
afb0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
afc0: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  NTL_MMAP_SIZE]].
afd0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
afe0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
aff0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
b000: 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72  used to query or
b010: 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69   set the.** maxi
b020: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
b030: 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65  tes that will be
b040: 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79   used for memory
b050: 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20  -mapped I/O..** 
b060: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
b070: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
b080: 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c  alue of type sql
b090: 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a  ite3_int64 that.
b0a0: 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72  ** is an advisor
b0b0: 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  y maximum number
b0c0: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
b0d0: 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20   file to memory 
b0e0: 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69  map.  The.** poi
b0f0: 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74  nter is overwrit
b100: 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64  ten with the old
b110: 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d   value.  The lim
b120: 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  it is not change
b130: 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75  d if.** the valu
b140: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69  e originally poi
b150: 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74  nted to is negat
b160: 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ive, and so the 
b170: 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a  current limit .*
b180: 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64  * can be queried
b190: 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61   by passing in a
b1a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
b1b0: 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20  gative number.  
b1c0: 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  This.** file-con
b1d0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74  trol is used int
b1e0: 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65  ernally to imple
b1f0: 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61  ment [PRAGMA mma
b200: 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  p_size]..**.** <
b210: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b220: 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65  L_TRACE]].** The
b230: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
b240: 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  RACE] file contr
b250: 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69  ol provides advi
b260: 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  sory information
b270: 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61  .** to the VFS a
b280: 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69  bout what the hi
b290: 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74  gher layers of t
b2a0: 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  he SQLite stack 
b2b0: 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68  are doing..** Th
b2c0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
b2d0: 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20  is used by some 
b2e0: 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61  VFS activity tra
b2f0: 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a  cing [shims]..**
b300: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b310: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
b320: 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68  ed string.  High
b330: 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65  er layers in the
b340: 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b  .** SQLite stack
b350: 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e   may generate in
b360: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20  stances of this 
b370: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a  file control if.
b380: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  ** the [SQLITE_U
b390: 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20  SE_FCNTL_TRACE] 
b3a0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
b3b0: 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
b3c0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b3d0: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
b3e0: 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ED]].** The [SQL
b3f0: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
b400: 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  VED] file contro
b410: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73  l interprets its
b420: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a   argument as a.*
b430: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
b440: 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77  integer and it w
b450: 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20  rites a boolean 
b460: 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
b470: 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f  r depending.** o
b480: 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  n whether or not
b490: 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65   the file has be
b4a0: 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65  en renamed, move
b4b0: 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69  d, or deleted si
b4c0: 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69  nce it.** was fi
b4d0: 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a  rst opened..**.*
b4e0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b4f0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
b500: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  ANDLE]].** The [
b510: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
b520: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f  32_SET_HANDLE] o
b530: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
b540: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
b550: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
b560: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
b570: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73  trol method to s
b580: 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e  wap the file han
b590: 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65  dle with the one
b5a0: 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
b5b0: 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  y the pArg argum
b5c0: 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62  ent.  This capab
b5d0: 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75  ility is used du
b5e0: 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20  ring testing.** 
b5f0: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
b600: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
b610: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20  hen SQLITE_TEST 
b620: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  is defined..**.*
b630: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b640: 43 4e 54 4c 5f 5a 49 50 56 46 53 5f 50 41 47 45  CNTL_ZIPVFS_PAGE
b650: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  R]].** The [SQLI
b660: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5f  TE_FCNTL_ZIPVFS_
b670: 50 41 47 45 52 5d 20 6f 70 63 6f 64 65 20 69 73  PAGER] opcode is
b680: 20 75 73 65 64 20 62 79 20 74 68 65 20 4f 54 41   used by the OTA
b690: 20 65 78 74 65 6e 73 69 6f 6e 20 77 68 65 6e 0a   extension when.
b6a0: 2a 2a 20 75 70 64 61 74 69 6e 67 20 61 20 7a 69  ** updating a zi
b6b0: 70 76 66 73 20 64 61 74 61 62 61 73 65 2e 0a 2a  pvfs database..*
b6c0: 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64  *.** </ul>.*/.#d
b6d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b6e0: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20  TL_LOCKSTATE    
b6f0: 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
b700: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
b710: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
b720: 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
b730: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
b740: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
b750: 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
b760: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
b770: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
b780: 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
b790: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
b7a0: 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20  IZE_HINT        
b7b0: 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
b7c0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48   SQLITE_FCNTL_CH
b7d0: 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20  UNK_SIZE        
b7e0: 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
b7f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
b800: 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  E_POINTER       
b810: 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
b820: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
b830: 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20  _OMITTED        
b840: 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
b850: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
b860: 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20  _AV_RETRY       
b870: 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
b880: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
b890: 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  T_WAL           
b8a0: 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
b8b0: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
b8c0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
b8d0: 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  11.#define SQLIT
b8e0: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20  E_FCNTL_VFSNAME 
b8f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
b900: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
b910: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
b920: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33  _OVERWRITE    13
b930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b940: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20  FCNTL_PRAGMA    
b950: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a               14.
b960: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b970: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
b980: 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23              15.#
b990: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b9a0: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
b9b0: 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64             16.#d
b9c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b9d0: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20  TL_MMAP_SIZE    
b9e0: 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 65            18.#de
b9f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ba00: 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 20  L_TRACE         
ba10: 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 66           19.#def
ba20: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ba30: 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20  _HAS_MOVED      
ba40: 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 66 69          20.#defi
ba50: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
ba60: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
ba70: 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e         21.#defin
ba80: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
ba90: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20  OMMIT_PHASETWO  
baa0: 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65        22.#define
bab0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
bac0: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20  N32_SET_HANDLE  
bad0: 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20       23.#define 
bae0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50  SQLITE_FCNTL_ZIP
baf0: 56 46 53 5f 50 41 47 45 52 20 20 20 20 20 20 20  VFS_PAGER       
bb00: 20 20 20 20 32 34 0a 0a 2f 2a 0a 2a 2a 20 43 41      24../*.** CA
bb10: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
bb20: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
bb30: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
bb40: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
bb50: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
bb60: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
bb70: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
bb80: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
bb90: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
bba0: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
bbb0: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
bbc0: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
bbd0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
bbe0: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
bbf0: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
bc00: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
bc10: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
bc20: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
bc30: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
bc40: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
bc50: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
bc60: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
bc70: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
bc80: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
bc90: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
bca0: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
bcb0: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
bcc0: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
bcd0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
bce0: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
bcf0: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
bd00: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
bd10: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
bd20: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
bd30: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
bd40: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
bd50: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
bd60: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
bd70: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
bd80: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
bd90: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
bda0: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
bdb0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
bdc0: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
bdd0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
bde0: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
bdf0: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
be00: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
be10: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
be20: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
be30: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
be40: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
be50: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
be60: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
be70: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
be80: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
be90: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
bea0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
beb0: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
bec0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
bed0: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
bee0: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
bef0: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
bf00: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
bf10: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
bf20: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
bf30: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
bf40: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
bf50: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
bf60: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
bf70: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
bf80: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
bf90: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
bfa0: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
bfb0: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
bfc0: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
bfd0: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
bfe0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
bff0: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
c000: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
c010: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
c020: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
c030: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
c040: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
c050: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
c060: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
c070: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
c080: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
c090: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
c0a0: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
c0b0: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
c0c0: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
c0d0: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
c0e0: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
c0f0: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
c100: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
c110: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
c120: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
c130: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
c140: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
c150: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
c160: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
c170: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
c180: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
c190: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
c1a0: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
c1b0: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
c1c0: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
c1d0: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
c1e0: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
c1f0: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
c200: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
c210: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
c220: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
c230: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
c240: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
c250: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
c260: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
c270: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
c280: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
c290: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
c2a0: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
c2b0: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
c2c0: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
c2d0: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
c2e0: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f  [[sqlite3_vfs.xO
c2f0: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65  pen]].** ^SQLite
c300: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
c310: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
c320: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
c330: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
c340: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
c350: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
c360: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
c370: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e  thname() with an
c380: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78   optional suffix
c390: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61   added..** ^If a
c3a0: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64   suffix is added
c3b0: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   to the zFilenam
c3c0: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20  e parameter, it 
c3d0: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20  will.** consist 
c3e0: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20  of a single "-" 
c3f0: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
c400: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68  ed by no more th
c410: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75  an.** 11 alphanu
c420: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22  meric and/or "-"
c430: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
c440: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20  ^SQLite further 
c450: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
c460: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
c470: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
c480: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
c490: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
c4a0: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f  alled. Because o
c4b0: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
c4c0: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  entence,.** the 
c4d0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
c4e0: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
c4f0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
c500: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
c510: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
c520: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
c530: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
c540: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
c550: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
c560: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   to xOpen is a N
c570: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
c580: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
c590: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65  nvent its own te
c5a0: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
c5b0: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65   the file.  ^Whe
c5c0: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
c5d0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
c5e0: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
c5f0: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
c600: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
c610: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
c620: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
c630: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
c640: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
c650: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
c660: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
c670: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
c680: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
c690: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
c6a0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
c6b0: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
c6c0: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
c6d0: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
c6e0: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
c6f0: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
c700: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
c710: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
c720: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
c730: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
c740: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
c750: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
c760: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
c770: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
c780: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
c790: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
c7a0: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
c7b0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
c7c0: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  be set..**.** ^(
c7d0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
c7e0: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
c7f0: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
c800: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
c810: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
c820: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
c830: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
c840: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
c850: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
c860: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
c870: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
c880: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
c890: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
c8a0: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
c8b0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c8c0: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
c8d0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
c8e0: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
c8f0: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
c900: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
c910: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
c920: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
c930: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  R_JOURNAL].** <l
c940: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c950: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _WAL].** </ul>)^
c960: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
c970: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
c980: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
c990: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
c9a0: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
c9b0: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
c9c0: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
c9d0: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
c9e0: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
c9f0: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
ca00: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
ca10: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
ca20: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
ca30: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
ca40: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
ca50: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
ca60: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
ca70: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
ca80: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
ca90: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
caa0: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
cab0: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
cac0: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
cad0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
cae0: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
caf0: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
cb00: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
cb10: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
cb20: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
cb30: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
cb40: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
cb50: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
cb60: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
cb70: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
cb80: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
cb90: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
cba0: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
cbb0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
cbc0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
cbd0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
cbe0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
cbf0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
cc00: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
cc10: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
cc20: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
cc30: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
cc40: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
cc50: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
cc60: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
cc70: 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65  is closed.  ^The
cc80: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
cc90: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
cca0: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
ccb0: 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61  TEMP databases a
ccc0: 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c  nd their journal
ccd0: 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20  s, transient.** 
cce0: 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73  databases, and s
ccf0: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
cd00: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
cd10: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
cd20: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
cd30: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
cd40: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
cd50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
cd60: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
cd70: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
cd80: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
cd90: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
cda0: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
cdb0: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
cdc0: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
cdd0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
cde0: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
cdf0: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
ce00: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
ce10: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
ce20: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
ce30: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
ce40: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
ce50: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
ce60: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
ce70: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
ce80: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
ce90: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
cea0: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
ceb0: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
cec0: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
ced0: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
cee0: 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69  ^At least szOsFi
cef0: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
cf00: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
cf10: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
cf20: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
cf30: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
cf40: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
cf50: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
cf60: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
cf70: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
cf80: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
cf90: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
cfa0: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
cfb0: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
cfc0: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61  it in.  Note tha
cfd0: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d  t.** the xOpen m
cfe0: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74  ethod must set t
cff0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
d000: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68  pMethods to eith
d010: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73  er.** a valid [s
d020: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
d030: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20  s] object or to 
d040: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73  NULL.  xOpen mus
d050: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65  t do.** this eve
d060: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  n if the open fa
d070: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70  ils.  SQLite exp
d080: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71  ects that the sq
d090: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
d0a0: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77  ods.** element w
d0b0: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74  ill be valid aft
d0c0: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73  er xOpen returns
d0d0: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
d0e0: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72  he success.** or
d0f0: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20   failure of the 
d100: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  xOpen call..**.*
d110: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
d120: 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68  xAccess]].** ^Th
d130: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
d140: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
d150: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
d160: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
d170: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
d180: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
d190: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
d1a0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
d1b0: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
d1c0: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
d1d0: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
d1e0: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
d1f0: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
d200: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
d210: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
d220: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54  st readable.   T
d230: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
d240: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
d250: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
d260: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
d270: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
d280: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
d290: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
d2a0: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
d2b0: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
d2c0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
d2d0: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
d2e0: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
d2f0: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
d300: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
d310: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
d320: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
d330: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
d340: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
d350: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
d360: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
d370: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
d380: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
d390: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
d3a0: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
d3b0: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
d3c0: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
d3d0: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
d3e0: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
d3f0: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
d400: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
d410: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
d420: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
d430: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
d440: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
d450: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
d460: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
d470: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
d480: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
d490: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
d4a0: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
d4b0: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
d4c0: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
d4d0: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
d4e0: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
d4f0: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
d500: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
d510: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
d520: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
d530: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
d540: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
d550: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
d560: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
d570: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
d580: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
d590: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
d5a0: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
d5b0: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
d5c0: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
d5d0: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
d5e0: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
d5f0: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
d600: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
d610: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
d620: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
d630: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
d640: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
d650: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
d660: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
d670: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
d680: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
d690: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
d6a0: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
d6b0: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
d6c0: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
d6d0: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
d6e0: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
d6f0: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
d700: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
d710: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
d720: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
d730: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
d740: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
d750: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
d760: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
d770: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
d780: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
d790: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
d7a0: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
d7b0: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
d7c0: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
d7d0: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
d7e0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
d7f0: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
d800: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
d810: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
d820: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
d830: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
d840: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
d850: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
d860: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
d870: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
d880: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
d890: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
d8a0: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
d8b0: 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
d8c0: 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
d8d0: 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
d8e0: 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
d8f0: 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
d900: 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
d910: 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
d920: 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
d930: 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
d940: 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
d950: 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
d960: 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
d970: 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
d980: 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
d990: 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
d9a0: 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
d9b0: 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
d9c0: 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
d9d0: 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
d9e0: 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
d9f0: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
da00: 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
da10: 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
da20: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
da30: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
da40: 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
da50: 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
da60: 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
da70: 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
da80: 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
da90: 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
daa0: 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
dab0: 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
dac0: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
dad0: 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
dae0: 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
daf0: 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
db00: 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
db10: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
db20: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
db30: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
db40: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
db50: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
db60: 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
db70: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
db80: 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
db90: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
dba0: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
dbb0: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
dbc0: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
dbd0: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
dbe0: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
dbf0: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
dc00: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
dc10: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
dc20: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
dc30: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
dc40: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
dc50: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
dc60: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
dc70: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
dc80: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
dc90: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
dca0: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
dcb0: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
dcc0: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
dcd0: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
dce0: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
dcf0: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
dd00: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
dd10: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
dd20: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
dd30: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
dd40: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
dd50: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
dd60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
dd70: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
dd80: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
dd90: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
dda0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
ddb0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
ddc0: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
ddd0: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
dde0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
ddf0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
de00: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
de10: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
de20: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
de30: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
de40: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
de50: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
de60: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
de70: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
de80: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
de90: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
dea0: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
deb0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
dec0: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
ded0: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
dee0: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
def0: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
df00: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
df10: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
df20: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
df30: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
df40: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
df50: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
df60: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
df70: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
df80: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
df90: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
dfa0: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
dfb0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
dfc0: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
dfd0: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
dfe0: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
dff0: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
e000: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
e010: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
e020: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
e030: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
e040: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
e050: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
e060: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
e070: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
e080: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
e090: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
e0a0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
e0b0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
e0c0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
e0d0: 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
e0e0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
e0f0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
e100: 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
e110: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
e120: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
e130: 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
e140: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
e150: 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
e160: 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
e170: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
e180: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e190: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
e1a0: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
e1b0: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
e1c0: 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
e1d0: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
e1e0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e1f0: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
e200: 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
e210: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
e220: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e230: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
e240: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
e250: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
e260: 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
e270: 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
e280: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
e290: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
e2a0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
e2b0: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73   figure versions
e2c0: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
e2d0: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
e2e0: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
e2f0: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
e300: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
e310: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
e320: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
e330: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
e340: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
e350: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
e360: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
e370: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
e380: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
e390: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
e3a0: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
e3b0: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
e3c0: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
e3d0: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
e3e0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
e3f0: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
e400: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
e410: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
e420: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
e430: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
e440: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
e450: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
e460: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
e470: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
e480: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
e490: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
e4a0: 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
e4b0: 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
e4c0: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
e4d0: 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
e4e0: 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
e4f0: 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
e500: 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
e510: 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
e520: 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
e530: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
e540: 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
e550: 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
e560: 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
e570: 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
e580: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
e590: 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
e5a0: 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
e5b0: 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
e5c0: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
e5d0: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
e5e0: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
e5f0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
e600: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
e610: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
e620: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
e630: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
e640: 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
e650: 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
e660: 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
e670: 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
e680: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
e690: 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
e6a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
e6b0: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
e6c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
e6d0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
e6e0: 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
e6f0: 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
e700: 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
e710: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
e720: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
e730: 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
e740: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e750: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
e760: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
e770: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
e780: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
e790: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
e7a0: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
e7b0: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
e7c0: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
e7d0: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
e7e0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
e7f0: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
e800: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
e810: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
e820: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
e830: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
e840: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
e850: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
e860: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
e870: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
e880: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
e890: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
e8a0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
e8b0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
e8c0: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
e8d0: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
e8e0: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
e8f0: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
e900: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
e910: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
e920: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
e930: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
e940: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
e950: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
e960: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
e970: 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70  n on the corresp
e980: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
e990: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
e9a0: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
e9b0: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
e9c0: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
e9d0: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
e9e0: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
e9f0: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
ea00: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
ea10: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
ea20: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
ea30: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
ea40: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
ea50: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
ea60: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
ea70: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
ea80: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
ea90: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
eaa0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
eab0: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
eac0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
ead0: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
eae0: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
eaf0: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
eb00: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
eb10: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
eb20: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
eb30: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
eb40: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
eb50: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
eb60: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
eb70: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
eb80: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
eb90: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
eba0: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
ebb0: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
ebc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
ebd0: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
ebe0: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
ebf0: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
ec00: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
ec10: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
ec20: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ec30: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
ec40: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
ec50: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
ec60: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
ec70: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
ec80: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
ec90: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
eca0: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
ecb0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
ecc0: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
ecd0: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
ece0: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
ecf0: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
ed00: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
ed10: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
ed20: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
ed30: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
ed40: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
ed50: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
ed60: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
ed70: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
ed80: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
ed90: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
eda0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
edb0: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
edc0: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
edd0: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
ede0: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
edf0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
ee00: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
ee10: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
ee20: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
ee30: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
ee40: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
ee50: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
ee60: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
ee70: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
ee80: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ee90: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
eea0: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
eeb0: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
eec0: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
eed0: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
eee0: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
eef0: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
ef00: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
ef10: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
ef20: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
ef30: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
ef40: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
ef50: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
ef60: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
ef70: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
ef80: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
ef90: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
efa0: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
efb0: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
efc0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
efd0: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
efe0: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
eff0: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
f000: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
f010: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
f020: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
f030: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
f040: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f050: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
f060: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
f070: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
f080: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
f090: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f0a0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
f0b0: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
f0c0: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
f0d0: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
f0e0: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
f0f0: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
f100: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
f110: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
f120: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
f130: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
f140: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
f150: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
f160: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
f170: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
f180: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
f190: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
f1a0: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
f1b0: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
f1c0: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
f1d0: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
f1e0: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
f1f0: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
f200: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
f210: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
f220: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
f230: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
f240: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
f250: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
f260: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f270: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
f280: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
f290: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
f2a0: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
f2b0: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
f2c0: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
f2d0: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
f2e0: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
f2f0: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
f300: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
f310: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
f320: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f330: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
f340: 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
f350: 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
f360: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
f370: 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
f380: 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
f390: 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
f3a0: 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
f3b0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f3c0: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
f3d0: 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
f3e0: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
f3f0: 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
f400: 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
f410: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
f420: 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
f430: 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
f440: 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
f450: 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
f460: 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
f470: 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
f480: 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
f490: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
f4a0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
f4b0: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
f4c0: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
f4d0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
f4e0: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
f4f0: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
f500: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
f510: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
f520: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
f530: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
f540: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
f550: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
f560: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
f570: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
f580: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
f590: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
f5a0: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
f5b0: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
f5c0: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
f5d0: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
f5e0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f5f0: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
f600: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
f610: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
f620: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
f630: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
f640: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
f650: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
f660: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
f670: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
f680: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
f690: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
f6a0: 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
f6b0: 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
f6c0: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
f6d0: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
f6e0: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
f6f0: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
f700: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
f710: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
f720: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
f730: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
f740: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
f750: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
f760: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
f770: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
f780: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
f790: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
f7a0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
f7b0: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
f7c0: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
f7d0: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
f7e0: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
f7f0: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
f800: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
f810: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
f820: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
f830: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
f840: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
f850: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
f860: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
f870: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
f880: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
f890: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
f8a0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
f8b0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
f8c0: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
f8d0: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
f8e0: 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
f8f0: 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
f900: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
f910: 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
f920: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
f930: 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
f940: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f950: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
f960: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
f970: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f980: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
f990: 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
f9a0: 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
f9b0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f9c0: 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
f9d0: 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
f9e0: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
f9f0: 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
fa00: 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
fa10: 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
fa20: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
fa30: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
fa40: 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
fa50: 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
fa60: 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
fa70: 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
fa80: 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
fa90: 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
faa0: 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
fab0: 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
fac0: 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
fad0: 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
fae0: 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
faf0: 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
fb00: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
fb10: 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
fb20: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
fb30: 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
fb40: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
fb50: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
fb60: 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
fb70: 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
fb80: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
fb90: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
fba0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
fbb0: 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
fbc0: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
fbd0: 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
fbe0: 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
fbf0: 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
fc00: 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ilure..*/.int sq
fc10: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fc20: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
fc30: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
fc40: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
fc50: 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69  os_init(void);.i
fc60: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nt sqlite3_os_en
fc70: 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
fc80: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
fc90: 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
fca0: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
fcb0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
fcc0: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
fcd0: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
fce0: 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
fcf0: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
fd00: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
fd10: 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
fd20: 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
fd30: 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
fd40: 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
fd50: 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
fd60: 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
fd70: 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
fd80: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
fd90: 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
fda0: 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
fdb0: 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
fdc0: 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
fdd0: 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
fde0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
fdf0: 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
fe00: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
fe10: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
fe20: 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
fe30: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
fe40: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
fe50: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
fe60: 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
fe70: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
fe80: 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
fe90: 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
fea0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
feb0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
fec0: 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
fed0: 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
fee0: 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
fef0: 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
ff00: 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
ff10: 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
ff20: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ff30: 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
ff40: 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
ff50: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
ff60: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
ff70: 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
ff80: 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
ff90: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
ffa0: 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
ffb0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
ffc0: 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
ffd0: 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
ffe0: 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
fff0: 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
10000 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
10010 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
10020 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
10030 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
10040 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
10050 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
10060 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
10070 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
10080 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
10090 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
100a0 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75  eger.** [configu
100b0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
100c0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
100d0 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
100e0 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
100f0 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
10100 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
10110 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
10120 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63  ending on the [c
10130 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10140 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
10150 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
10160 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
10170 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10180 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
10190 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
101a0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
101b0 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
101c0 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
101d0 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
101e0 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
101f0 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
10200 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
10210 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
10220 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
10230 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
10240 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
10250 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
10260 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
10270 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  nnections.**.** 
10280 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
10290 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
102a0 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
102b0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
102c0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
102d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
102e0 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
102f0 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
10300 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
10310 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
10320 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
10330 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
10340 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
10350 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
10360 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
10370 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
10380 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
10390 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
103a0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
103b0 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
103c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
103d0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
103e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
103f0 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
10400 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
10410 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
10420 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
10430 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10440 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
10450 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
10460 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
10470 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
10480 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
10490 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
104a0 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
104b0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
104c0 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
104d0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
104e0 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
104f0 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
10500 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
10510 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
10520 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
10530 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
10540 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
10550 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
10560 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
10570 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
10580 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
10590 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
105a0 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
105b0 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
105c0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
105d0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
105e0 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
105f0 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
10600 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
10610 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
10620 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
10630 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
10640 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
10650 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
10660 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
10670 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
10680 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
10690 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
106a0 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
106b0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
106c0 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
106d0 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
106e0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
106f0 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
10700 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
10710 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
10720 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
10730 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
10740 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
10750 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
10760 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
10770 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
10780 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
10790 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
107a0 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
107b0 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
107c0 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
107d0 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
107e0 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
107f0 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
10800 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
10810 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
10820 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
10830 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
10840 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
10850 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
10860 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
10870 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
10880 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
10890 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
108a0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
108b0 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
108c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
108d0 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
108e0 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
108f0 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
10900 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
10910 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
10920 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
10930 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
10940 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
10950 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
10960 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
10970 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
10980 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
10990 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
109a0 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
109b0 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
109c0 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
109d0 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
109e0 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
109f0 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
10a00 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
10a10 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
10a20 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
10a30 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
10a40 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
10a50 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
10a60 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
10a70 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
10a80 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
10a90 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
10aa0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
10ab0 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
10ac0 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
10ad0 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
10ae0 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
10af0 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
10b00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
10b10 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
10b20 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
10b30 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
10b40 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
10b50 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
10b60 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
10b70 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
10b80 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
10b90 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
10ba0 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
10bb0 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
10bc0 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
10bd0 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
10be0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
10bf0 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
10c00 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
10c10 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
10c20 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
10c30 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
10c40 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
10c50 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
10c60 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
10c70 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
10c80 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
10c90 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
10ca0 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
10cb0 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
10cc0 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
10cd0 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
10ce0 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
10cf0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
10d00 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
10d10 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
10d20 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
10d30 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
10d40 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
10d50 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
10d60 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
10d70 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
10d80 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
10d90 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
10da0 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
10db0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
10dc0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
10dd0 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
10de0 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
10df0 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
10e00 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
10e10 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
10e20 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
10e30 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
10e40 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
10e50 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
10e60 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
10e70 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
10e80 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
10e90 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
10ea0 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
10eb0 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
10ec0 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
10ed0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
10ee0 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
10ef0 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
10f00 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
10f10 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
10f20 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65  ASTER] mutex whe
10f30 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  n it invokes.** 
10f40 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
10f50 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d  , so the xInit m
10f60 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62  ethod need not b
10f70 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  e threadsafe.  T
10f80 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20  he.** xShutdown 
10f90 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63  method is only c
10fa0 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  alled from [sqli
10fb0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
10fc0 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  so it does.** no
10fd0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72  t need to be thr
10fe0 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20  eadsafe either. 
10ff0 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d   For all other m
11000 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a  ethods, SQLite.*
11010 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  * holds the [SQL
11020 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
11030 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c  _MEM] mutex as l
11040 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53  ong as the.** [S
11050 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
11060 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72  STATUS] configur
11070 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
11080 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68  turned on (which
11090 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66  .** it is by def
110a0 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65  ault) and so the
110b0 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74   methods are aut
110c0 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61  omatically seria
110d0 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65  lized..** Howeve
110e0 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f  r, if [SQLITE_CO
110f0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
11100 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  is disabled, the
11110 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d  n the other.** m
11120 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74  ethods must be t
11130 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73  hreadsafe or els
11140 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e  e make their own
11150 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f   arrangements fo
11160 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69  r.** serializati
11170 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
11180 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
11190 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20  ke xInit() more 
111a0 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75  than once withou
111b0 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67  t an intervening
111c0 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75  .** call to xShu
111d0 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65  tdown()..*/.type
111e0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
111f0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
11200 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11210 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
11220 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
11230 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
11240 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
11250 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
11260 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
11270 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
11280 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
11290 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
112a0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
112b0 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
112c0 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
112d0 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
112e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
112f0 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
11300 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
11310 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
11320 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
11330 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
11340 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
11350 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
11360 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
11370 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
11380 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
11390 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
113a0 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
113b0 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
113c0 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
113d0 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
113e0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
113f0 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
11400 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
11410 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
11420 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
11430 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
11440 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
11450 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
11460 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
11470 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
11480 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45  on Options.** KE
11490 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75  YWORDS: {configu
114a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a  ration option}.*
114b0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
114c0 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
114d0 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
114e0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
114f0 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
11500 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
11510 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11520 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
11530 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
11540 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
11550 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11560 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
11570 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
11580 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
11590 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
115a0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
115b0 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
115c0 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
115d0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
115e0 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
115f0 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
11600 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11610 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
11620 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
11630 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
11640 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
11650 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
11660 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
11670 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
11680 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
11690 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
116a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
116b0 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
116c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
116d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
116e0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d  G_SINGLETHREAD]]
116f0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11700 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
11710 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
11720 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
11730 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
11740 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
11750 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
11760 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
11770 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
11780 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
11790 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
117a0 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
117b0 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
117c0 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
117d0 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
117e0 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
117f0 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
11800 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11810 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
11820 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11830 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
11840 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
11850 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
11860 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
11870 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
11880 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
11890 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
118a0 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
118b0 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
118c0 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
118d0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
118e0 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
118f0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
11900 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
11910 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
11920 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
11930 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11940 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
11950 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
11960 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  TITHREAD]] <dt>S
11970 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
11980 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
11990 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
119a0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
119b0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
119c0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
119d0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
119e0 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
119f0 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
11a00 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
11a10 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
11a20 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
11a30 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
11a40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11a50 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
11a60 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
11a70 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
11a80 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
11a90 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
11aa0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
11ab0 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
11ac0 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
11ad0 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
11ae0 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
11af0 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
11b00 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
11b10 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
11b20 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
11b30 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
11b40 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
11b50 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
11b60 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
11b70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11b80 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
11b90 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
11ba0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
11bb0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
11bc0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
11bd0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
11be0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
11bf0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
11c00 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
11c10 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
11c20 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
11c30 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
11c40 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11c50 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
11c60 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
11c70 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
11c80 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
11c90 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
11ca0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11cb0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
11cc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
11cd0 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53  RIALIZED]] <dt>S
11ce0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
11cf0 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
11d00 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
11d10 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
11d20 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
11d30 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
11d40 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
11d50 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69  mode] to Seriali
11d60 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  zed. In other wo
11d70 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e  rds, this option
11d80 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
11d90 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
11da0 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
11db0 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
11dc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11dd0 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
11de0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
11df0 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
11e00 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
11e10 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
11e20 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
11e30 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
11e40 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
11e50 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
11e60 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
11e70 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
11e80 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
11e90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
11ea0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
11eb0 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
11ec0 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
11ed0 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
11ee0 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
11ef0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11f00 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
11f10 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
11f20 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
11f30 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
11f40 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
11f50 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
11f60 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
11f70 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
11f80 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
11f90 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
11fa0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
11fb0 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
11fc0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
11fd0 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a  set the Serializ
11fe0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
11ff0 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
12000 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
12010 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
12020 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
12030 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
12040 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
12050 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72  IALIZED configur
12060 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
12070 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12080 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
12090 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
120a0 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
120b0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
120c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
120d0 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
120e0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
120f0 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61  t which is .** a
12100 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
12110 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
12120 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12130 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
12140 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
12150 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
12160 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
12170 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
12180 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f  tion routines to
12190 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
121a0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  e of.** the memo
121b0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
121c0 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
121d0 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c  o SQLite.)^ ^SQL
121e0 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73  ite makes.** its
121f0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
12200 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74  y of the content
12210 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12220 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
12230 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72  ructure.** befor
12240 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  e the [sqlite3_c
12250 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65  onfig()] call re
12260 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  turns.</dd>.**.*
12270 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12280 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  G_GETMALLOC]] <d
12290 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
122a0 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
122b0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
122c0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
122d0 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65  LLOC option take
122e0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
122f0 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
12300 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
12310 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
12320 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
12330 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
12340 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
12350 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
12360 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
12370 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
12380 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
12390 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
123a0 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
123b0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
123c0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
123d0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
123e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
123f0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
12400 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
12410 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
12420 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12430 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
12440 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
12450 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
12460 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
12470 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
12480 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c  STATUS]] <dt>SQL
12490 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
124a0 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
124b0 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
124c0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f  NFIG_MEMSTATUS o
124d0 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67  ption takes sing
124e0 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
124f0 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65  ype int,.** inte
12500 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
12510 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
12520 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
12530 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
12540 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  f.** memory allo
12550 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
12560 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79  s. ^(When memory
12570 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
12580 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69  istics are.** di
12590 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c  sabled, the foll
125a0 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
125b0 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e  erfaces become n
125c0 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a  on-operational:.
125d0 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  **   <ul>.**   <
125e0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
125f0 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20  ory_used()].**  
12600 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
12610 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
12620 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
12630 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
12640 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20  limit64()].**   
12650 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
12660 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75  atus()].**   </u
12670 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20  l>)^.** ^Memory 
12680 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
12690 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65  stics are enable
126a0 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c  d by default unl
126b0 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  ess SQLite is.**
126c0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
126d0 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d  SQLITE_DEFAULT_M
126e0 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77  EMSTATUS]=0 in w
126f0 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79  hich case memory
12700 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  .** allocation s
12710 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
12720 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
12730 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  t..** </dd>.**.*
12740 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12750 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e  G_SCRATCH]] <dt>
12760 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
12770 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RATCH</dt>.** <d
12780 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
12790 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70  ONFIG_SCRATCH op
127a0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
127b0 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
127c0 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51  uffer.** that SQ
127d0 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
127e0 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e   scratch memory.
127f0 20 20 5e 28 54 68 65 72 65 20 61 72 65 20 74 68    ^(There are th
12800 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ree arguments.**
12810 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
12820 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f  G_SCRATCH:  A po
12830 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a  inter an 8-byte.
12840 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72  ** aligned memor
12850 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68  y buffer from wh
12860 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20  ich the scratch 
12870 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c  allocations will
12880 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68   be.** drawn, th
12890 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73  e size of each s
128a0 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
128b0 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74  n (sz),.** and t
128c0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
128d0 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c  r of scratch all
128e0 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a  ocations (N).)^.
128f0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
12900 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
12910 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d  pointer to an 8-
12920 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66  byte aligned buf
12930 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  fer.** of at lea
12940 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
12950 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
12960 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65  ite will not use
12970 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73   more than one s
12980 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70  cratch buffers p
12990 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53  er thread..** ^S
129a0 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
129b0 20 72 65 71 75 65 73 74 20 61 20 73 63 72 61 74   request a scrat
129c0 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69  ch buffer that i
129d0 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a  s more than 6.**
129e0 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62   times the datab
129f0 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a  ase page size..*
12a00 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65  * ^If SQLite nee
12a10 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f  ds needs additio
12a20 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  nal.** scratch m
12a30 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61  emory beyond wha
12a40 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
12a50 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   this configurat
12a60 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ion option, then
12a70 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
12a80 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20  lloc()] will be 
12a90 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
12aa0 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64  he memory needed
12ab0 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  .<p>.** ^When th
12ac0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72  e application pr
12ad0 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e  ovides any amoun
12ae0 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d  t of scratch mem
12af0 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c  ory using.** SQL
12b00 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
12b10 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64  CH, SQLite avoid
12b20 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61  s unnecessary la
12b30 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rge.** [sqlite3_
12b40 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f  malloc|heap allo
12b50 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69  cations]..** Thi
12b60 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73  s can help [Robs
12b70 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74  on proof|prevent
12b80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12b90 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65  on failures] due
12ba0 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67   to heap.** frag
12bb0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77  mentation in low
12bc0 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64  -memory embedded
12bd0 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64   systems..** </d
12be0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12bf0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
12c00 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
12c10 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
12c20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
12c30 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
12c40 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f  _PAGECACHE optio
12c50 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
12c60 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
12c70 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  er.** that SQLit
12c80 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68  e can use for th
12c90 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
12ca0 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64  cache with the d
12cb0 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63  efault page.** c
12cc0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
12cd0 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63  ion.  .** This c
12ce0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f  onfiguration sho
12cf0 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
12d00 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
12d10 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a  n-define page.**
12d20 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
12d30 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20  ation is loaded 
12d40 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
12d50 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
12d60 5d 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  ].** configurati
12d70 6f 6e 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54  on option..** ^T
12d80 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
12d90 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49  rguments to SQLI
12da0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
12db0 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  CHE: A pointer t
12dc0 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67  o.** 8-byte alig
12dd0 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  ned.** memory, t
12de0 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
12df0 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
12e00 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
12e10 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
12e20 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
12e30 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
12e40 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
12e50 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
12e60 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
12e70 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
12e80 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73   and 65536) plus
12e90 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65   some extra byte
12ea0 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61  s for each.** pa
12eb0 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65  ge header.  ^The
12ec0 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61   number of extra
12ed0 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79   bytes needed by
12ee0 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72   the page header
12ef0 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72  .** can be deter
12f00 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20  mined using the 
12f10 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
12f20 43 41 43 48 45 5f 48 44 52 53 5a 5d 20 6f 70 74  CACHE_HDRSZ] opt
12f30 69 6f 6e 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ion .** to [sqli
12f40 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
12f50 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73  * ^It is harmles
12f60 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68  s, apart from th
12f70 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c  e wasted memory,
12f80 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70  .** for the sz p
12f90 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c  arameter to be l
12fa0 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73  arger than neces
12fb0 73 61 72 79 2e 20 20 54 68 65 20 66 69 72 73 74  sary.  The first
12fc0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
12fd0 75 6c 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  uld pointer to a
12fe0 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
12ff0 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
13000 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 74 20 6c   that.** is at l
13010 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
13020 6f 66 20 6d 65 6d 6f 72 79 2c 20 6f 74 68 65 72  of memory, other
13030 77 69 73 65 20 73 75 62 73 65 71 75 65 6e 74 20  wise subsequent 
13040 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75  behavior is.** u
13050 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51  ndefined..** ^SQ
13060 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
13070 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65  e memory provide
13080 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
13090 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73  rgument to satis
130a0 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79  fy its.** memory
130b0 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66   needs for the f
130c0 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61  irst N pages tha
130d0 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63  t it adds to cac
130e0 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f  he.  ^If additio
130f0 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  nal.** page cach
13100 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64  e memory is need
13110 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ed beyond what i
13120 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
13130 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a  is option, then.
13140 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  ** SQLite goes t
13150 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
13160 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64  c()] for the add
13170 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20  itional storage 
13180 73 70 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  space.</dd>.**.*
13190 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
131a0 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c  G_HEAP]] <dt>SQL
131b0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
131c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
131d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
131e0 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63  HEAP option spec
131f0 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
13200 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a  emory buffer .**
13210 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
13220 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  l use for all of
13230 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
13240 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
13250 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74  eeds.** beyond t
13260 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f  hose provided fo
13270 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
13280 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
13290 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
132a0 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
132b0 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  * ^The SQLITE_CO
132c0 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
132d0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
132e0 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  le if SQLite is 
132f0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68  compiled.** with
13300 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
13310 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
13320 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  or [SQLITE_ENABL
13330 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72  E_MEMSYS5] and r
13340 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
13350 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f  E_ERROR] if invo
13360 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  ked otherwise..*
13370 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72  * ^There are thr
13380 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
13390 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
133a0 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65  AP:.** An 8-byte
133b0 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
133c0 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
133d0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
133e0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
133f0 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
13400 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
13410 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
13420 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
13430 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
13440 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
13450 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
13460 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
13470 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
13480 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
13490 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
134a0 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
134b0 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
134c0 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
134d0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
134e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
134f0 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
13500 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
13510 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74   not NULL then t
13520 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d  he alternative m
13530 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
13540 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f  or is engaged to
13550 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53   handle all of S
13560 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c  QLites memory al
13570 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a  location needs..
13580 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69  ** The first poi
13590 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
135a0 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62   pointer) must b
135b0 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
135c0 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61  8-byte.** bounda
135d0 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
135e0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
135f0 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  ite will be unde
13600 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69  fined..** The mi
13610 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
13620 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20   size is capped 
13630 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e  at 2**12. Reason
13640 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66  able values.** f
13650 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  or the minimum a
13660 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61  llocation size a
13670 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20  re 2**5 through 
13680 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  2**8.</dd>.**.**
13690 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
136a0 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  _MUTEX]] <dt>SQL
136b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
136c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
136d0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
136e0 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  G_MUTEX option t
136f0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
13700 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
13710 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
13720 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
13730 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
13740 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
13750 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ture..** The arg
13760 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20  ument specifies 
13770 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
13780 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74  level mutex rout
13790 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a  ines to be used.
137a0 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20  ** in place the 
137b0 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62  mutex routines b
137c0 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
137d0 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
137e0 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  es a copy of.** 
137f0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
13800 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
13810 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
13820 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20  ture before the 
13830 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
13840 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65  te3_config()] re
13850 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74  turns. ^If SQLit
13860 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
13870 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
13880 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
13890 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
138a0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
138b0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
138c0 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
138d0 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
138e0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
138f0 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
13900 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
13910 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
13920 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
13930 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f  _CONFIG_MUTEX co
13940 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13950 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
13960 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
13970 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
13980 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13990 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
139a0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
139b0 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
139c0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
139d0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74  FIG_GETMUTEX opt
139e0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
139f0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
13a00 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
13a10 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
13a20 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
13a30 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
13a40 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
13a50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
13a60 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
13a70 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
13a80 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
13a90 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
13aa0 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  ex routines.)^.*
13ab0 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
13ac0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
13ad0 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
13ae0 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
13af0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
13b00 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
13b10 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
13b20 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
13b30 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
13b40 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
13b50 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20   for example.   
13b60 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
13b70 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
13b80 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
13b90 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
13ba0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
13bb0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
13bc0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
13bd0 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
13be0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
13bf0 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
13c00 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
13c10 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
13c20 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
13c30 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13c40 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67  _GETMUTEX config
13c50 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
13c60 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
13c70 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
13c80 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13c90 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
13ca0 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  DE]] <dt>SQLITE_
13cb0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
13cc0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
13cd0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
13ce0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69  G_LOOKASIDE opti
13cf0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
13d00 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
13d10 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66  rmine.** the def
13d20 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f  ault size of loo
13d30 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e  kaside memory on
13d40 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20   each [database 
13d50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
13d60 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
13d70 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
13d80 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
13d90 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20  ide buffer slot 
13da0 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69  and the second i
13db0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
13dc0 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74  ** slots allocat
13dd0 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ed to each datab
13de0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29  ase connection.)
13df0 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46  ^  ^(SQLITE_CONF
13e00 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20  IG_LOOKASIDE.** 
13e10 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61  sets the <i>defa
13e20 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
13e30 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
13e40 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
13e50 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f  KASIDE].** optio
13e60 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  n to [sqlite3_db
13e70 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62  _config()] can b
13e80 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  e used to change
13e90 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a   the lookaside.*
13ea0 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
13eb0 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f  on individual co
13ec0 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64  nnections.)^ </d
13ed0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13ee0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
13ef0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13f00 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74  NFIG_PCACHE2</dt
13f10 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
13f20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
13f30 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
13f40 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13f50 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
13f60 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
13f70 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
13f80 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
13f90 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
13fa0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
13fb0 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61  e interface to a
13fc0 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
13fd0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
13fe0 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  n.)^.** ^SQLite 
13ff0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
14000 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  the [sqlite3_pca
14010 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
14020 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ject.</dd>.**.**
14030 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14040 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64  _GETPCACHE2]] <d
14050 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14060 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  GETPCACHE2</dt>.
14070 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
14080 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
14090 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
140a0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
140b0 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
140c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
140d0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
140e0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
140f0 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
14100 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72  es of.** the cur
14110 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20  rent page cache 
14120 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
14130 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
14140 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
14150 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
14160 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OG]] <dt>SQLITE_
14170 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a  CONFIG_LOG</dt>.
14180 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49  ** <dd> The SQLI
14190 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
141a0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
141b0 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51  configure the SQ
141c0 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b  Lite.** global [
141d0 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28  error log]..** (
141e0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
141f0 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
14200 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
14210 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
14220 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
14230 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
14240 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
14250 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
14260 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
14270 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
14280 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
14290 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
142a0 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
142b0 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
142c0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
142d0 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
142e0 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
142f0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
14300 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
14310 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
14320 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
14330 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
14340 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
14350 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
14360 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
14370 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
14380 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
14390 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
143a0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
143b0 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
143c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
143d0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
143e0 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
143f0 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
14400 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
14410 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
14420 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
14430 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
14440 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
14450 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
14460 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
14470 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
14480 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
14490 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
144a0 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
144b0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
144c0 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
144d0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
144e0 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
144f0 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
14500 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
14510 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
14520 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
14530 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
14540 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
14550 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
14560 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
14570 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
14580 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
14590 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
145a0 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
145b0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
145c0 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
145d0 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
145e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
145f0 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
14600 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
14610 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
14620 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14630 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d  ITE_CONFIG_URI]]
14640 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14650 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28  IG_URI.** <dd>^(
14660 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14670 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b  G_URI option tak
14680 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14690 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
146a0 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f  ..** If non-zero
146b0 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c  , then URI handl
146c0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
146d0 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20  enabled. If the 
146e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72  parameter is zer
146f0 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68  o,.** then URI h
14700 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
14710 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20  lly disabled.)^ 
14720 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  ^If URI handling
14730 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
14740 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c  enabled, all fil
14750 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f  enames passed to
14760 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
14770 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
14780 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
14790 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72  te3_open16()] or
147a0 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73  .** specified as
147b0 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48   part of [ATTACH
147c0 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69  ] commands are i
147d0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
147e0 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a  Is, regardless.*
147f0 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  * of whether or 
14800 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  not the [SQLITE_
14810 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
14820 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64  s set when the d
14830 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
14840 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
14850 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61   ^If it is globa
14860 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69  lly disabled, fi
14870 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f  lenames are.** o
14880 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20  nly interpreted 
14890 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53  as URIs if the S
148a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66  QLITE_OPEN_URI f
148b0 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
148c0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
148d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
148e0 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75  ened. ^(By defau
148f0 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  lt, URI handling
14900 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
14910 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65  disabled. The de
14920 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20  fault value may 
14930 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f  be changed by co
14940 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65  mpiling with the
14950 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  .** [SQLITE_USE_
14960 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69  URI] symbol defi
14970 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ned.)^.**.** [[S
14980 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
14990 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
149a0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
149b0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
149c0 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e  DEX_SCAN.** <dd>
149d0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
149e0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
149f0 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61  X_SCAN option ta
14a00 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74  kes a single int
14a10 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  eger.** argument
14a20 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70   which is interp
14a30 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65  reted as a boole
14a40 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65  an in order to e
14a50 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
14a60 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63  .** the use of c
14a70 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
14a80 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
14a90 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72  cans in the quer
14aa0 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20  y optimizer..** 
14ab0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  ^The default set
14ac0 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e  ting is determin
14ad0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51  ed.** by the [SQ
14ae0 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52  LITE_ALLOW_COVER
14af0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20  ING_INDEX_SCAN] 
14b00 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
14b10 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a  ion, or is "on".
14b20 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69  ** if that compi
14b30 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
14b40 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68  s omitted..** Th
14b50 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73  e ability to dis
14b60 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20  able the use of 
14b70 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
14b80 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
14b90 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61  scans.** is beca
14ba0 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65  use some incorre
14bb0 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63  ctly coded legac
14bc0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d  y applications m
14bd0 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e  ight malfunction
14be0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74  .** when the opt
14bf0 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61  imization is ena
14c00 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67  bled.  Providing
14c10 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a   the ability to.
14c20 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f  ** disable the o
14c30 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f  ptimization allo
14c40 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75  ws the older, bu
14c50 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ggy application 
14c60 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  code to work.** 
14c70 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65  without change e
14c80 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76  ven with newer v
14c90 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
14ca0 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  e..**.** [[SQLIT
14cb0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d  E_CONFIG_PCACHE]
14cc0 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ] [[SQLITE_CONFI
14cd0 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a  G_GETPCACHE]].**
14ce0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14cf0 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51  IG_PCACHE and SQ
14d00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
14d10 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68  CACHE.** <dd> Th
14d20 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20  ese options are 
14d30 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f  obsolete and sho
14d40 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
14d50 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20  by new code..** 
14d60 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65  They are retaine
14d70 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
14d80 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75  compatibility bu
14d90 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73  t are now no-ops
14da0 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
14db0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14dc0 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74  _SQLLOG]].** <dt
14dd0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
14de0 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69  QLLOG.** <dd>Thi
14df0 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  s option is only
14e00 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71   available if sq
14e10 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  lite is compiled
14e20 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
14e30 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c  LITE_ENABLE_SQLL
14e40 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f  OG] pre-processo
14e50 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e  r macro defined.
14e60 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
14e70 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65  ent should.** be
14e80 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
14e90 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65  function of type
14ea0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
14eb0 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68  qlite3*,const ch
14ec0 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68  ar*, int)..** Th
14ed0 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20  e second should 
14ee0 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  be of type (void
14ef0 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  *). The callback
14f00 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74   is invoked by t
14f10 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e  he library.** in
14f20 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20   three separate 
14f30 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69  circumstances, i
14f40 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
14f50 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
14f60 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
14f70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65  arameter. If the
14f80 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
14f90 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65  r is 0, then the
14fa0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
14fb0 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61  tion.** passed a
14fc0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
14fd0 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62  ument has just b
14fe0 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20  een opened. The 
14ff0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
15000 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75  * points to a bu
15010 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ffer containing 
15020 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
15030 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
15040 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f  le. If the.** fo
15050 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
15060 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51  s 1, then the SQ
15070 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
15080 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
15090 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74  eter.** points t
150a0 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20  o has just been 
150b0 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66  executed. Or, if
150c0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
150d0 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e  meter is 2, then
150e0 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  .** the connecti
150f0 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20  on being passed 
15100 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
15110 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67  rameter is being
15120 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20   closed. The.** 
15130 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
15140 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49  is passed NULL I
15150 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e  n this case.  An
15160 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e   example of usin
15170 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67  g this.** config
15180 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63  uration option c
15190 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68  an be seen in th
151a0 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63  e "test_sqllog.c
151b0 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e  " source file in
151c0 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61  .** the canonica
151d0 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  l SQLite source 
151e0 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tree.</dd>.**.**
151f0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15200 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
15210 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15220 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c  G_MMAP_SIZE.** <
15230 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  dd>^SQLITE_CONFI
15240 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65  G_MMAP_SIZE take
15250 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74  s two 64-bit int
15260 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e  eger (sqlite3_in
15270 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74  t64) values.** t
15280 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61  hat are the defa
15290 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69  ult mmap size li
152a0 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74  mit (the default
152b0 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20   setting for.** 
152c0 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
152d0 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69  e]) and the maxi
152e0 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70  mum allowed mmap
152f0 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20   size limit..** 
15300 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  ^The default set
15310 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72  ting can be over
15320 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64  ridden by each d
15330 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15340 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68  on using.** eith
15350 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d  er the [PRAGMA m
15360 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e  map_size] comman
15370 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74  d, or by using t
15380 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
15390 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66  NTL_MMAP_SIZE] f
153a0 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28  ile control.  ^(
153b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  The maximum allo
153c0 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a  wed mmap size.**
153d0 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c   will be silentl
153e0 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e  y truncated if n
153f0 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74  ecessary so that
15400 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63   it does not exc
15410 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  eed the.** compi
15420 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20  le-time maximum 
15430 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79  mmap size set by
15440 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
15450 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63  MAX_MMAP_SIZE] c
15460 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
15470 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74  on.)^.** ^If eit
15480 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  her argument to 
15490 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e  this option is n
154a0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
154b0 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  at argument is.*
154c0 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73  * changed to its
154d0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65   compile-time de
154e0 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  fault..**.** [[S
154f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
15500 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a  32_HEAPSIZE]].**
15510 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15520 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
15530 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  E.** <dd>^The SQ
15540 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
15550 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f  2_HEAPSIZE optio
15560 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
15570 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
15580 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72  .** compiled for
15590 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68   Windows with th
155a0 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f  e [SQLITE_WIN32_
155b0 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63  MALLOC] pre-proc
155c0 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64  essor macro.** d
155d0 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f  efined. ^SQLITE_
155e0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
155f0 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32  PSIZE takes a 32
15600 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
15610 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74  teger value.** t
15620 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68  hat specifies th
15630 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
15640 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65  f the created he
15650 61 70 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  ap..** </dl>.**.
15660 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15670 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d  IG_PCACHE_HDRSZ]
15680 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
15690 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
156a0 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  RSZ.** <dd>^The 
156b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
156c0 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f  ACHE_HDRSZ optio
156d0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
156e0 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
156f0 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
15700 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61   to an integer a
15710 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74  nd writes into t
15720 68 61 74 20 69 6e 74 65 67 65 72 20 74 68 65 20  hat integer the 
15730 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a  number of extra.
15740 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70 61 67  ** bytes per pag
15750 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65  e required for e
15760 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c  ach page in [SQL
15770 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
15780 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d  ACHE]..** The am
15790 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70  ount of extra sp
157a0 61 63 65 20 72 65 71 75 69 72 65 64 20 63 61 6e  ace required can
157b0 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e   change dependin
157c0 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65  g on the compile
157d0 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61  r,.** target pla
157e0 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74  tform, and SQLit
157f0 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  e version..**.**
15800 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15810 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e  _PMASZ]].** <dt>
15820 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
15830 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  ASZ.** <dd>^The 
15840 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
15850 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  ASZ option takes
15860 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
15870 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
15880 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  an unsigned inte
15890 67 65 72 20 61 6e 64 20 73 65 74 73 20 74 68 65  ger and sets the
158a0 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69   "Minimum PMA Si
158b0 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74  ze" for the mult
158c0 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72  ithreaded.** sor
158d0 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65  ter to that inte
158e0 67 65 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ger.  The defaul
158f0 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69  t minimum PMA Si
15900 7a 65 20 69 73 20 73 65 74 20 62 79 20 74 68 65  ze is set by the
15910 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54  .** [SQLITE_SORT
15920 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c  ER_PMASZ] compil
15930 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20  e-time option.  
15940 4e 65 77 20 74 68 72 65 61 64 73 20 61 72 65 20  New threads are 
15950 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68  launched.** to h
15960 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70  elp with sort op
15970 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75  erations when mu
15980 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f 72 74  ltithreaded sort
15990 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65  ing.** is enable
159a0 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52  d (using the [PR
159b0 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f  AGMA threads] co
159c0 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61  mmand) and the a
159d0 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74  mount of content
159e0 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64  .** to be sorted
159f0 20 65 78 63 65 65 64 73 20 74 68 65 20 70 61 67   exceeds the pag
15a00 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65  e size times the
15a10 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a   minimum of the.
15a20 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65  ** [PRAGMA cache
15a30 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61  _size] setting a
15a40 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a  nd this value..*
15a50 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
15a60 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15a70 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31  _SINGLETHREAD  1
15a80 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
15a90 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15aa0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20  G_MULTITHREAD   
15ab0 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  2  /* nil */.#de
15ac0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15ad0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20  IG_SERIALIZED   
15ae0 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   3  /* nil */.#d
15af0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15b00 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  FIG_MALLOC      
15b10 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    4  /* sqlite3_
15b20 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
15b30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15b40 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
15b50 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
15b60 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
15b70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15b80 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
15b90 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64        6  /* void
15ba0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
15bb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15bc0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
15bd0 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f  CHE     7  /* vo
15be0 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
15bf0 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
15c00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
15c10 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20            8  /* 
15c20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65  void*, int nByte
15c30 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65  , int min */.#de
15c40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15c50 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20  IG_MEMSTATUS    
15c60 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a   9  /* boolean *
15c70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15c80 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20  _CONFIG_MUTEX   
15c90 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69       10  /* sqli
15ca0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
15cb0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
15cc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15cd0 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20  UTEX     11  /* 
15ce0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
15cf0 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65  thods* */./* pre
15d00 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43  viously SQLITE_C
15d10 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43  ONFIG_CHUNKALLOC
15d20 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77   12 which is now
15d30 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65   unused. */ .#de
15d40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15d50 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
15d60 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a  13  /* int int *
15d70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15d80 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20  _CONFIG_PCACHE  
15d90 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f       14  /* no-o
15da0 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
15db0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
15dc0 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e  ACHE    15  /* n
15dd0 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20  o-op */.#define 
15de0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15df0 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f  G          16  /
15e00 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a  * xFunc, void* *
15e10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15e20 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20  _CONFIG_URI     
15e30 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20       17  /* int 
15e40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15e50 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
15e60 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c        18  /* sql
15e70 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
15e80 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  ods2* */.#define
15e90 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
15ea0 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20  ETPCACHE2   19  
15eb0 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
15ec0 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
15ed0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15ee0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
15ef0 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20  DEX_SCAN 20  /* 
15f00 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
15f10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
15f20 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a  LOG       21  /*
15f30 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20   xSqllog, void* 
15f40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15f50 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
15f60 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c  ZE    22  /* sql
15f70 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69  ite3_int64, sqli
15f80 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65  te3_int64 */.#de
15f90 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15fa0 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
15fb0 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e  E      23  /* in
15fc0 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69  t nByte */.#defi
15fd0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15fe0 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20  _PCACHE_HDRSZ   
15ff0 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20       24  /* int 
16000 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  *psz */.#define 
16010 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
16020 41 53 5a 20 20 20 20 20 20 20 20 20 20 20 20 20  ASZ             
16030 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65    25  /* unsigne
16040 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 0a  d int szPma */..
16050 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
16060 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
16070 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
16080 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
16090 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
160a0 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
160b0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
160c0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
160d0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
160e0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
160f0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
16100 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
16110 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
16120 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
16130 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
16140 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
16150 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
16160 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
16170 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
16180 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
16190 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
161a0 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
161b0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
161c0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
161d0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
161e0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
161f0 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
16200 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
16210 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
16220 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
16230 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
16240 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
16250 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
16260 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
16270 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
16280 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
16290 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
162a0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
162b0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
162c0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
162d0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
162e0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
162f0 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
16300 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
16310 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
16320 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
16330 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
16340 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
16350 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
16360 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
16370 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
16380 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
16390 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
163a0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
163b0 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
163c0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
163d0 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
163e0 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
163f0 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
16400 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
16410 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
16420 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
16430 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
16440 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
16450 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
16460 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
16470 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
16480 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
16490 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
164a0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
164b0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
164c0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
164d0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
164e0 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
164f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
16500 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
16510 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
16520 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
16530 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
16540 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
16550 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
16560 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
16570 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
16580 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
16590 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
165a0 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
165b0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
165c0 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
165d0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
165e0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
165f0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
16600 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
16610 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
16620 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
16630 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
16640 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
16650 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  r multiple of 8.
16660 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64    ^(The lookasid
16670 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66  e memory.** conf
16680 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20  iguration for a 
16690 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
166a0 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ion can only be 
166b0 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61  changed when tha
166c0 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  t.** connection 
166d0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
166e0 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65   using lookaside
166f0 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f   memory, or in o
16700 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68  ther words.** wh
16710 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20  en the "current 
16720 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20  value" returned 
16730 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64  by.** [sqlite3_d
16740 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c  b_status](D,[SQL
16750 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
16760 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65  SIDE],...) is ze
16770 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ro..** Any attem
16780 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  pt to change the
16790 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
167a0 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  y configuration 
167b0 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a  when lookaside.*
167c0 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75  * memory is in u
167d0 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f  se leaves the co
167e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68  nfiguration unch
167f0 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
16800 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  s .** [SQLITE_BU
16810 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  SY].)^</dd>.**.*
16820 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
16830 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
16840 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  Y</dt>.** <dd> ^
16850 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
16860 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
16870 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66   disable the enf
16880 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b  orcement of.** [
16890 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
168a0 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65  traints].  There
168b0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
168c0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
168d0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
168e0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
168f0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
16900 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46  s 0 to disable F
16910 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a  K enforcement,.*
16920 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
16930 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
16940 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ent or negative 
16950 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f  to leave FK enfo
16960 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61  rcement.** uncha
16970 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e  nged.  The secon
16980 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
16990 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
169a0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
169b0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
169c0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
169d0 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e  te whether FK en
169e0 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66  forcement is off
169f0 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77   or on.** follow
16a00 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
16a10 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
16a20 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
16a30 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
16a40 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
16a50 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
16a60 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
16a70 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
16a80 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
16a90 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
16aa0 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74  ABLE_TRIGGER</dt
16ab0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
16ac0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
16ad0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
16ae0 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47  ble [CREATE TRIG
16af0 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e  GER | triggers].
16b00 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
16b10 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
16b20 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
16b30 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
16b40 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
16b50 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
16b60 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73  disable triggers
16b70 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
16b80 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73   enable triggers
16b90 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
16ba0 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
16bb0 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
16bc0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
16bd0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
16be0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
16bf0 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
16c00 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
16c10 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
16c20 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65  her triggers are
16c30 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
16c40 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
16c50 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
16c60 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
16c70 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
16c80 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
16c90 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74  which case the t
16ca0 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69  rigger setting i
16cb0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
16cc0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
16cd0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
16ce0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
16cf0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20  G_LOOKASIDE     
16d00 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a    1001  /* void*
16d10 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
16d20 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
16d30 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20  FIG_ENABLE_FKEY 
16d40 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74      1002  /* int
16d50 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
16d60 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
16d70 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20  _ENABLE_TRIGGER 
16d80 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e   1003  /* int in
16d90 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t* */.../*.** CA
16da0 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
16db0 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
16dc0 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
16dd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
16de0 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
16df0 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69  lt_codes() routi
16e00 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
16e10 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65  sables the.** [e
16e20 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
16e30 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
16e40 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78   SQLite. ^The ex
16e50 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
16e60 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
16e70 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
16e80 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
16e90 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a  mpatibility..*/.
16ea0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
16eb0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
16ec0 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
16ed0 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
16ee0 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
16ef0 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a  sert Rowid.**.**
16f00 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
16f10 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c  most SQLite tabl
16f20 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b  es (except for [
16f30 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
16f40 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20  ables).** has a 
16f50 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
16f60 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
16f70 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b  key called the [
16f80 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d  ROWID | "rowid"]
16f90 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20  . ^The rowid is 
16fa0 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
16fb0 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
16fc0 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
16fd0 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
16fe0 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
16ff0 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
17000 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
17010 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
17020 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
17030 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20  mns. ^If.** the 
17040 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
17050 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
17060 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
17070 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
17080 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
17090 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
170a0 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  wid..**.** ^The 
170b0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
170c0 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74  ert_rowid(D) int
170d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
170e0 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
170f0 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  e .** most recen
17100 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  t successful [IN
17110 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77  SERT] into a row
17120 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72  id table or [vir
17130 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f  tual table].** o
17140 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
17150 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73  ction D..** ^Ins
17160 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f  erts into [WITHO
17170 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
17180 20 61 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65   are not recorde
17190 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63  d..** ^If no suc
171a0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
171b0 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62  s into rowid tab
171c0 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72  les.** have ever
171d0 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65   occurred on the
171e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
171f0 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e  tion D, .** then
17200 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
17210 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65  sert_rowid(D) re
17220 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
17230 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52  * ^(If an [INSER
17240 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  T] occurs within
17250 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 69   a trigger or wi
17260 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20  thin a [virtual 
17270 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64  table].** method
17280 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  , then this rout
17290 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ine will return 
172a0 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
172b0 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72  he inserted.** r
172c0 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ow as long as th
172d0 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
172e0 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
172f0 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  d is running..**
17300 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72   But once the tr
17310 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
17320 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e   table method en
17330 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  ds, the value re
17340 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68  turned .** by th
17350 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72  is routine rever
17360 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61  ts to what it wa
17370 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69  s before the tri
17380 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a  gger or virtual.
17390 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  ** table method 
173a0 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  began.)^.**.** ^
173b0 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74  An [INSERT] that
173c0 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20   fails due to a 
173d0 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
173e0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a  tion is not a.**
173f0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
17400 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f  ERT] and does no
17410 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
17420 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
17430 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20  his.** routine. 
17440 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52   ^Thus INSERT OR
17450 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52   FAIL, INSERT OR
17460 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20   IGNORE, INSERT 
17470 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20  OR ROLLBACK,.** 
17480 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42  and INSERT OR AB
17490 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e  ORT make no chan
174a0 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72  ges to the retur
174b0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a  n value of this.
174c0 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20  ** routine when 
174d0 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20  their insertion 
174e0 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49  fails.  ^(When I
174f0 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
17500 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  .** encounters a
17510 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
17520 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e  ation, it does n
17530 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a  ot fail.  The.**
17540 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65   INSERT continue
17550 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  s to completion 
17560 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72  after deleting r
17570 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a  ows that caused.
17580 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  ** the constrain
17590 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53  t problem so INS
175a0 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77  ERT OR REPLACE w
175b0 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67  ill always chang
175c0 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20  e.** the return 
175d0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e  value of this in
175e0 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a  terface.)^.**.**
175f0 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73   ^For the purpos
17600 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  es of this routi
17610 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  ne, an [INSERT] 
17620 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  is considered to
17630 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75  .** be successfu
17640 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  l even if it is 
17650 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c  subsequently rol
17660 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
17670 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
17680 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53   accessible to S
17690 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69  QL statements vi
176a0 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69  a the.** [last_i
176b0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51  nsert_rowid() SQ
176c0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
176d0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
176e0 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73   thread performs
176f0 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20   a new [INSERT] 
17700 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64  on the same.** d
17710 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17720 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71  on while the [sq
17730 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
17740 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75  t_rowid()].** fu
17750 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
17760 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67  g and thus chang
17770 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65  es the last inse
17780 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74  rt [rowid],.** t
17790 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
177a0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
177b0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
177c0 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e  owid()] is.** un
177d0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
177e0 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20  might not equal 
177f0 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f  either the old o
17800 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73  r the new.** las
17810 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
17820 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
17830 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  64 sqlite3_last_
17840 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
17850 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
17860 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
17870 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
17880 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
17890 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
178a0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
178b0 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66  er of rows modif
178c0 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ied, inserted or
178d0 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74  .** deleted by t
178e0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
178f0 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
17900 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
17910 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
17920 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
17930 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63   connection spec
17940 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c  ified by the onl
17950 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  y parameter..** 
17960 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f  ^Executing any o
17970 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c  ther type of SQL
17980 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
17990 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76  not modify the v
179a0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
179b0 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f   by this functio
179c0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63  n..**.** ^Only c
179d0 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65  hanges made dire
179e0 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45  ctly by the INSE
179f0 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
17a00 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61  LETE statement a
17a10 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
17a20 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61   - auxiliary cha
17a30 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
17a40 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
17a50 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20   triggers], .** 
17a60 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
17a70 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43  ions] or [REPLAC
17a80 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  E] constraint re
17a90 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74  solution are not
17aa0 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a   counted..** .**
17ab0 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69   Changes to a vi
17ac0 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
17ad0 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b  rcepted by .** [
17ae0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
17af0 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20  er | INSTEAD OF 
17b00 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f  triggers] are no
17b10 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20  t counted. ^The 
17b20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e  value .** return
17b30 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68  ed by sqlite3_ch
17b40 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74  anges() immediat
17b50 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53  ely after an INS
17b60 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a  ERT, UPDATE or .
17b70 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  ** DELETE statem
17b80 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65  ent run on a vie
17b90 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  w is always zero
17ba0 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d  . Only changes m
17bb0 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20  ade to real .** 
17bc0 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74  tables are count
17bd0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73  ed..**.** Things
17be0 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69   are more compli
17bf0 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c  cated if the sql
17c00 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66  ite3_changes() f
17c10 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78  unction is.** ex
17c20 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74  ecuted while a t
17c30 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69  rigger program i
17c40 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20  s running. This 
17c50 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68  may happen if th
17c60 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65  e.** program use
17c70 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  s the [changes()
17c80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20   SQL function], 
17c90 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72  or if some other
17ca0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
17cb0 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71  ction invokes sq
17cc0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
17cd0 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74  directly. Essent
17ce0 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75  ially:.** .** <u
17cf0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42  l>.**   <li> ^(B
17d00 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61  efore entering a
17d10 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
17d20 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
17d30 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  ned by.**       
17d40 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
17d50 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73  () function is s
17d60 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20  aved. After the 
17d70 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
17d80 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66  .**        has f
17d90 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69  inished, the ori
17da0 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72  ginal value is r
17db0 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a  estored.)^.** .*
17dc0 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69  *   <li> ^(Withi
17dd0 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  n a trigger prog
17de0 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c  ram each INSERT,
17df0 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45   UPDATE and DELE
17e00 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74  TE .**        st
17e10 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65  atement sets the
17e20 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
17e30 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  by sqlite3_chang
17e40 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  es() .**        
17e50 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  upon completion 
17e60 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f  as normal. Of co
17e70 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65  urse, this value
17e80 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64   will not includ
17e90 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79  e .**        any
17ea0 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d   changes perform
17eb0 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65  ed by sub-trigge
17ec0 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74  rs, as the sqlit
17ed0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a  e3_changes() .**
17ee0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69          value wi
17ef0 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20  ll be saved and 
17f00 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65  restored after e
17f10 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20  ach sub-trigger 
17f20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f  has run.)^.** </
17f30 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73  ul>.** .** ^This
17f40 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74   means that if t
17f50 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c  he changes() SQL
17f60 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69   function (or si
17f70 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a  milar) is used.*
17f80 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49  * by the first I
17f90 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
17fa0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
17fb0 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
17fc0 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72  er, it .** retur
17fd0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20  ns the value as 
17fe0 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c  set when the cal
17ff0 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62  ling statement b
18000 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a  egan executing..
18010 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65  ** ^If it is use
18020 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
18030 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75  or subsequent su
18040 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ch statement wit
18050 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a  hin a trigger .*
18060 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76  * program, the v
18070 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65  alue returned re
18080 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65  flects the numbe
18090 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
180a0 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72  ed by the .** pr
180b0 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55  evious INSERT, U
180c0 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
180d0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
180e0 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
180f0 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
18100 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
18110 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
18120 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
18130 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
18140 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
18150 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
18160 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
18170 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
18180 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
18190 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
181a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
181b0 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
181c0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
181d0 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
181e0 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
181f0 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
18200 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
18210 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
18220 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
18230 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
18240 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18250 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
18260 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
18270 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
18280 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74  on returns the t
18290 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72  otal number of r
182a0 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f  ows inserted, mo
182b0 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c  dified or.** del
182c0 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53  eted by all [INS
182d0 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f  ERT], [UPDATE] o
182e0 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
182f0 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a  ments completed.
18300 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74  ** since the dat
18310 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18320 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63   was opened, inc
18330 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65  luding those exe
18340 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74  cuted as.** part
18350 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67   of trigger prog
18360 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67  rams. ^Executing
18370 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
18380 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
18390 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66  .** does not aff
183a0 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65  ect the value re
183b0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
183c0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
183d0 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67  )..** .** ^Chang
183e0 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  es made as part 
183f0 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  of [foreign key 
18400 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63  actions] are inc
18410 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  luded in the.** 
18420 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65  count, but those
18430 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
18440 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
18450 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
18460 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e  re.** not. ^Chan
18470 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
18480 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74  at are intercept
18490 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46  ed by INSTEAD OF
184a0 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72   triggers .** ar
184b0 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
184c0 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  * .** See also t
184d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
184e0 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
184f0 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
18500 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
18510 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
18520 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
18530 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
18540 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
18550 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
18560 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
18570 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18580 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
18590 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
185a0 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
185b0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
185c0 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
185d0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
185e0 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
185f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
18600 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
18610 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
18620 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
18630 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
18640 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  g Query.**.** ^T
18650 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
18660 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
18670 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
18680 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
18690 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
186a0 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
186b0 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
186c0 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
186d0 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
186e0 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
186f0 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
18700 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
18710 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
18720 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
18730 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
18740 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
18750 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
18760 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
18770 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
18780 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
18790 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
187a0 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
187b0 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
187c0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
187d0 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
187e0 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
187f0 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
18800 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
18810 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
18820 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
18830 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
18840 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
18850 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
18860 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
18870 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
18880 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
18890 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
188a0 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
188b0 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
188c0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
188d0 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
188e0 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
188f0 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
18900 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
18910 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
18920 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
18930 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
18940 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
18950 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
18960 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
18970 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
18980 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
18990 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
189a0 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
189b0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
189c0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
189d0 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
189e0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
189f0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
18a00 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
18a10 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
18a20 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
18a30 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
18a40 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18a50 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
18a60 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
18a70 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
18a80 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
18a90 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
18aa0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
18ab0 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
18ac0 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
18ad0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
18ae0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
18af0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
18b00 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
18b10 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
18b20 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
18b30 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
18b40 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
18b50 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
18b60 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
18b70 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
18b80 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
18b90 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
18ba0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
18bb0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
18bc0 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
18bd0 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
18be0 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
18bf0 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
18c00 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
18c10 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
18c20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
18c30 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
18c40 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
18c50 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
18c60 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
18c70 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
18c80 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
18c90 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
18ca0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
18cb0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
18cc0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
18cd0 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
18ce0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
18cf0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
18d00 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
18d10 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
18d20 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
18d30 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
18d40 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
18d50 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76  ely happen..*/.v
18d60 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
18d70 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
18d80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18d90 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
18da0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
18db0 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
18dc0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
18dd0 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
18de0 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
18df0 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
18e00 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
18e10 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
18e20 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
18e30 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
18e40 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
18e50 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
18e60 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
18e70 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
18e80 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
18e90 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
18ea0 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
18eb0 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
18ec0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
18ed0 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
18ee0 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
18ef0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
18f00 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
18f10 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
18f20 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
18f30 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
18f40 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
18f50 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
18f60 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
18f70 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
18f80 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
18f90 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
18fa0 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
18fb0 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
18fc0 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
18fd0 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
18fe0 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
18ff0 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
19000 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
19010 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
19020 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
19030 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
19040 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
19050 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
19060 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
19070 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
19080 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
19090 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
190a0 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
190b0 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
190c0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
190d0 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
190e0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
190f0 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
19100 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
19110 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
19120 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
19130 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
19140 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
19150 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
19160 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
19170 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
19180 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
19190 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
191a0 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
191b0 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
191c0 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
191d0 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
191e0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
191f0 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
19200 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
19210 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
19220 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
19230 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
19240 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
19250 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
19260 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
19270 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
19280 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
19290 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
192a0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
192b0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
192c0 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
192d0 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
192e0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
192f0 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
19300 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
19310 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
19320 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
19330 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
19340 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
19350 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
19360 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
19370 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
19380 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
19390 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
193a0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
193b0 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
193c0 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
193d0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
193e0 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
193f0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
19400 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
19410 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
19420 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
19430 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
19440 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
19450 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
19460 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73  * KEYWORDS: {bus
19470 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
19480 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65  ck} {busy handle
19490 72 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r}.**.** ^The sq
194a0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
194b0 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e  er(D,X,P) routin
194c0 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
194d0 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20  k function X.** 
194e0 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
194f0 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d  voked with argum
19500 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a  ent P whenever.*
19510 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
19520 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 61  made to access a
19530 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
19540 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
19550 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
19560 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20  nection] D when 
19570 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
19580 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
19590 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65   the table locke
195a0 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  d..** The sqlite
195b0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
195c0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
195d0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a  ed to implement.
195e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
195f0 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20  _timeout()] and 
19600 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
19610 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  eout]..**.** ^If
19620 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
19630 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
19640 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
19650 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
19660 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
19670 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
19680 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
19690 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
196a0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
196b0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
196c0 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
196d0 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
196e0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
196f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
19700 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
19710 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
19720 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
19730 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
19740 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
19750 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
19760 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
19770 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
19780 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
19790 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
197a0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
197b0 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
197c0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
197d0 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
197e0 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72  d previously for
197f0 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e   the same lockin
19800 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
19810 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
19820 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
19830 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
19840 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
19850 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
19860 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
19870 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69   [SQLITE_BUSY] i
19880 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f  s returned.** to
19890 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
198a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
198b0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
198c0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
198d0 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
198e0 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
198f0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
19900 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70  nd the cycle rep
19910 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eats..**.** The 
19920 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75  presence of a bu
19930 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20  sy handler does 
19940 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68  not guarantee th
19950 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  at it will be in
19960 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68  voked.** when th
19970 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74  ere is lock cont
19980 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69  ention. ^If SQLi
19990 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
199a0 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
199b0 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
199c0 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
199d0 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
199e0 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
199f0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
19a00 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  BUSY].** to the 
19a10 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74  application inst
19a20 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
19a30 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e  the .** busy han
19a40 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
19a50 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
19a60 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
19a70 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
19a80 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
19a90 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
19aa0 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
19ab0 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
19ac0 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
19ad0 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
19ae0 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
19af0 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
19b00 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
19b10 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
19b20 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
19b30 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
19b40 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
19b50 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
19b60 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
19b70 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
19b80 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
19b90 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
19ba0 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
19bb0 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
19bc0 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
19bd0 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
19be0 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
19bf0 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
19c00 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
19c10 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
19c20 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
19c30 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
19c40 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
19c50 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
19c60 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
19c70 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
19c80 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
19c90 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
19ca0 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
19cb0 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
19cc0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
19cd0 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
19ce0 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
19cf0 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
19d00 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
19d10 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
19d20 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ned for each.** 
19d30 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
19d40 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20  tion].  Setting 
19d50 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
19d60 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a  er clears any.**
19d70 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
19d80 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74  handler.)^  ^Not
19d90 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
19da0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
19db0 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76  eout()].** or ev
19dc0 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41  aluating [PRAGMA
19dd0 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d   busy_timeout=N]
19de0 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65   will change the
19df0 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72  .** busy handler
19e00 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20   and thus clear 
19e10 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73  any previously s
19e20 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  et busy handler.
19e30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20  .**.** The busy 
19e40 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20  callback should 
19e50 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74  not take any act
19e60 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66  ions which modif
19e70 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  y the.** databas
19e80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
19e90 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
19ea0 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20  sy handler.  In 
19eb0 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20  other words,.** 
19ec0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19ed0 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
19ee0 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  t.  Any such act
19ef0 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
19f00 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
19f10 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
19f20 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
19f30 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
19f40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19f50 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
19f60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
19f70 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
19f80 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
19f90 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
19fa0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
19fb0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
19fc0 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
19fd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
19fe0 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
19ff0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
1a000 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
1a010 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1a020 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
1a030 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
1a040 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
1a050 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
1a060 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
1a070 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
1a080 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
1a090 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
1a0a0 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
1a0b0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
1a0c0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
1a0d0 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
1a0e0 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
1a0f0 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
1a100 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1a110 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
1a120 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
1a130 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
1a140 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
1a150 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
1a160 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  E_BUSY]..**.** ^
1a170 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
1a180 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
1a190 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
1a1a0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
1a1b0 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
1a1c0 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
1a1d0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
1a1e0 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
1a1f0 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
1a200 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
1a210 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1a220 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e  onnection] at an
1a230 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
1a240 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
1a250 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
1a260 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
1a270 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1a280 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
1a290 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
1a2a0 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
1a2b0 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
1a2c0 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29  ler is cleared.)
1a2d0 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
1a2e0 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  :  [PRAGMA busy_
1a2f0 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20  timeout].*/.int 
1a300 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1a310 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  eout(sqlite3*, i
1a320 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  nt ms);../*.** C
1a330 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69  API3REF: Conveni
1a340 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f  ence Routines Fo
1a350 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65  r Running Querie
1a360 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  s.**.** This is 
1a370 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  a legacy interfa
1a380 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65  ce that is prese
1a390 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rved for backwar
1a3a0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
1a3b0 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73  ..** Use of this
1a3c0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
1a3d0 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  t recommended..*
1a3e0 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a  *.** Definition:
1a3f0 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62   A <b>result tab
1a400 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79  le</b> is memory
1a410 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20   data structure 
1a420 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a  created by the.*
1a430 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  * [sqlite3_get_t
1a440 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63  able()] interfac
1a450 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62  e.  A result tab
1a460 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a  le records the.*
1a470 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79  * complete query
1a480 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e   results from on
1a490 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65  e or more querie
1a4a0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  s..**.** The tab
1a4b0 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20  le conceptually 
1a4c0 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  has a number of 
1a4d0 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73  rows and columns
1a4e0 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20  .  But.** these 
1a4f0 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20  numbers are not 
1a500 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75  part of the resu
1a510 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e  lt table itself.
1a520 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65    These.** numbe
1a530 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20  rs are obtained 
1a540 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74  separately.  Let
1a550 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   N be the number
1a560 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20   of rows.** and 
1a570 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  M be the number 
1a580 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a  of columns..**.*
1a590 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1a5a0 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
1a5b0 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f  pointers to zero
1a5c0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1a5d0 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  8 strings..** Th
1a5e0 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20  ere are (N+1)*M 
1a5f0 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  elements in the 
1a600 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73  array.  The firs
1a610 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69  t M pointers poi
1a620 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65  nt.** to zero-te
1a630 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
1a640 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74   that  contain t
1a650 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20  he names of the 
1a660 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20  columns..** The 
1a670 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65  remaining entrie
1a680 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71  s all point to q
1a690 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e  uery results.  N
1a6a0 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c  ULL values resul
1a6b0 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69  t.** in NULL poi
1a6c0 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65  nters.  All othe
1a6d0 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20  r values are in 
1a6e0 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f  their UTF-8 zero
1a6f0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
1a700 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61  tring representa
1a710 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64  tion as returned
1a720 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
1a730 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
1a740 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1a750 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20  e might consist 
1a760 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d  of one or more m
1a770 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1a780 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  s..** It is not 
1a790 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72  safe to pass a r
1a7a0 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65  esult table dire
1a7b0 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33  ctly to [sqlite3
1a7c0 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72  _free()]..** A r
1a7d0 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75  esult table shou
1a7e0 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ld be deallocate
1a7f0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1a800 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a  _free_table()]..
1a810 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78  **.** ^(As an ex
1a820 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73  ample of the res
1a830 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74  ult table format
1a840 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72  , suppose a quer
1a850 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61  y result.** is a
1a860 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1a870 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1a880 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d  e>.**        Nam
1a890 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a  e        | Age.*
1a8a0 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d  *        -------
1a8b0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1a8c0 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65  .**        Alice
1a8d0 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20         | 43.**  
1a8e0 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20        Bob       
1a8f0 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20    | 28.**       
1a900 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32   Cindy       | 2
1a910 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  1.** </pre></blo
1a920 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1a930 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c  here are two col
1a940 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74  umn (M==2) and t
1a950 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29  hree rows (N==3)
1a960 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72  .  Thus the.** r
1a970 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20  esult table has 
1a980 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70  8 entries.  Supp
1a990 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74  ose the result t
1a9a0 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a  able is stored.*
1a9b0 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61  * in an array na
1a9c0 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54  mes azResult.  T
1a9d0 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c  hen azResult hol
1a9e0 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a  ds this content:
1a9f0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1aa00 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1aa10 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1aa20 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20  0] = "Name";.** 
1aa30 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1aa40 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a  #91;1] = "Age";.
1aa50 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1aa60 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69  lt&#91;2] = "Ali
1aa70 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ce";.**        a
1aa80 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d  zResult&#91;3] =
1aa90 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "43";.**       
1aaa0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d   azResult&#91;4]
1aab0 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20   = "Bob";.**    
1aac0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1aad0 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20  ;5] = "28";.**  
1aae0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1aaf0 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b  91;6] = "Cindy";
1ab00 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1ab10 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31  ult&#91;7] = "21
1ab20 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
1ab30 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
1ab40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
1ab50 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74  et_table() funct
1ab60 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e  ion evaluates on
1ab70 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d  e or more.** sem
1ab80 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64  icolon-separated
1ab90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1aba0 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  in the zero-term
1abb0 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20  inated UTF-8.** 
1abc0 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e  string of its 2n
1abd0 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
1abe0 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
1abf0 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a   table to the.**
1ac00 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69   pointer given i
1ac10 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  n its 3rd parame
1ac20 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ter..**.** After
1ac30 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1ac40 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
1ac50 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  th the result fr
1ac60 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  om sqlite3_get_t
1ac70 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75  able(),.** it mu
1ac80 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75  st pass the resu
1ac90 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72  lt table pointer
1aca0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
1acb0 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65  _table() in orde
1acc0 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20  r to.** release 
1acd0 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  the memory that 
1ace0 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42  was malloced.  B
1acf0 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61  ecause of the wa
1ad00 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
1ad10 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70  3_malloc()] happ
1ad20 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74  ens within sqlit
1ad30 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20  e3_get_table(), 
1ad40 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66  the calling.** f
1ad50 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  unction must not
1ad60 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71   try to call [sq
1ad70 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69  lite3_free()] di
1ad80 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a  rectly.  Only.**
1ad90 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1ada0 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20  able()] is able 
1adb0 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  to release the m
1adc0 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61  emory properly a
1add0 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a  nd safely..**.**
1ade0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
1adf0 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61  _table() interfa
1ae00 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ce is implemente
1ae10 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61  d as a wrapper a
1ae20 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
1ae30 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20  3_exec()].  The 
1ae40 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1ae50 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  e() routine does
1ae60 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73   not have access
1ae70 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72  .** to any inter
1ae80 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75  nal data structu
1ae90 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  res of SQLite.  
1aea0 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65  It uses only the
1aeb0 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72   public.** inter
1aec0 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72  face defined her
1aed0 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75  e.  As a consequ
1aee0 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61  ence, errors tha
1aef0 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a  t occur in the.*
1af00 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20  * wrapper layer 
1af10 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69  outside of the i
1af20 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33  nternal [sqlite3
1af30 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72  _exec()] call ar
1af40 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74  e not.** reflect
1af50 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74  ed in subsequent
1af60 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1af70 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72  e3_errcode()] or
1af80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
1af90 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  msg()]..*/.int s
1afa0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1afb0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1afc0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
1afd0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
1afe0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1aff0 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20  Sql,     /* SQL 
1b000 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
1b010 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a  */.  char ***paz
1b020 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65  Result,    /* Re
1b030 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
1b040 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52  ry */.  int *pnR
1b050 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ow,           /*
1b060 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1b070 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
1b080 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ere */.  int *pn
1b090 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f  Column,        /
1b0a0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1b0b0 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
1b0c0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
1b0d0 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20  r **pzErrmsg    
1b0e0 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
1b0f0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1b100 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1b110 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20  free_table(char 
1b120 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a  **result);../*.*
1b130 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d  * CAPI3REF: Form
1b140 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69  atted String Pri
1b150 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  nting Functions.
1b160 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1b170 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c  ines are work-al
1b180 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69  ikes of the "pri
1b190 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66  ntf()" family of
1b1a0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72   functions.** fr
1b1b0 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
1b1c0 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  C library..**.**
1b1d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70   ^The sqlite3_mp
1b1e0 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69  rintf() and sqli
1b1f0 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72  te3_vmprintf() r
1b200 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68  outines write th
1b210 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  eir.** results i
1b220 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
1b230 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
1b240 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20  3_malloc()]..** 
1b250 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
1b260 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77  rned by these tw
1b270 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  o routines shoul
1b280 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64  d be.** released
1b290 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   by [sqlite3_fre
1b2a0 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75  e()].  ^Both rou
1b2b0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a  tines return a.*
1b2c0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
1b2d0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1b2e0 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74  c()] is unable t
1b2f0 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67  o allocate enoug
1b300 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68  h.** memory to h
1b310 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e  old the resultin
1b320 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  g string..**.** 
1b330 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e  ^(The sqlite3_sn
1b340 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1b350 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22   is similar to "
1b360 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d  snprintf()" from
1b370 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
1b380 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65   C library.  The
1b390 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74   result is writt
1b3a0 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62  en into the.** b
1b3b0 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61  uffer supplied a
1b3c0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1b3d0 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a  ameter whose siz
1b3e0 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a  e is given by.**
1b3f0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
1b400 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20  eter. Note that 
1b410 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
1b420 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61  .** first two pa
1b430 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65  rameters is reve
1b440 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e  rsed from snprin
1b450 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73  tf().)^  This is
1b460 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61   an.** historica
1b470 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20  l accident that 
1b480 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20  cannot be fixed 
1b490 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
1b4a0 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
1b4b0 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28  mpatibility.  ^(
1b4c0 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73  Note also that s
1b4d0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1b4e0 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70  ).** returns a p
1b4f0 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75  ointer to its bu
1b500 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  ffer instead of 
1b510 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
1b520 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75   characters actu
1b530 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74  ally written int
1b540 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20  o the buffer.)^ 
1b550 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a   We admit that.*
1b560 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
1b570 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74  characters writt
1b580 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f  en would be a mo
1b590 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e  re useful return
1b5a0 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65  .** value but we
1b5b0 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74   cannot change t
1b5c0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
1b5d0 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
1b5e0 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77  rintf().** now w
1b5f0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
1b600 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1b610 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73  *.** ^As long as
1b620 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65   the buffer size
1b630 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
1b640 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73   zero, sqlite3_s
1b650 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61  nprintf().** gua
1b660 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
1b670 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79   buffer is alway
1b680 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
1b690 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a  d.  ^The first.*
1b6a0 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
1b6b0 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
1b6c0 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
1b6d0 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
1b6e0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
1b6f0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
1b700 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
1b710 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
1b720 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
1b730 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
1b740 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
1b750 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1b760 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  _vsnprintf() rou
1b770 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67  tine is a vararg
1b780 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c  s version of sql
1b790 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e  ite3_snprintf().
1b7a0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1b7b0 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d  tines all implem
1b7c0 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  ent some additio
1b7d0 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a  nal formatting.*
1b7e0 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61  * options that a
1b7f0 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
1b800 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73  nstructing SQL s
1b810 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c  tatements..** Al
1b820 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70  l of the usual p
1b830 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69  rintf() formatti
1b840 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79  ng options apply
1b850 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20  .  In addition, 
1b860 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20  there.** is are 
1b870 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20  "%q", "%Q", and 
1b880 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%z" options..**
1b890 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74  .** ^(The %q opt
1b8a0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1b8b0 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62  s in that it sub
1b8c0 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74  stitutes a nul-t
1b8d0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1b8e0 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67  ing from the arg
1b8f0 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74  ument list.  But
1b900 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73   %q also doubles
1b910 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72   every '\'' char
1b920 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20  acter..** %q is 
1b930 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65  designed for use
1b940 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67   inside a string
1b950 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20   literal.)^  By 
1b960 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
1b970 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
1b980 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
1b990 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
1b9a0 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
1b9b0 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
1b9c0 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
1b9d0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73   For example, as
1b9e0 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20  sume the string 
1b9f0 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63  variable zText c
1ba00 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
1ba10 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1ba20 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1ba30 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
1ba40 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
1ba50 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
1ba60 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1ba70 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
1ba80 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
1ba90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
1baa0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1bab0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1bac0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
1bad0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
1bae0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
1baf0 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
1bb00 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
1bb10 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
1bb20 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
1bb30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
1bb40 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
1bb50 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1bb60 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
1bb70 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
1bb80 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
1bb90 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
1bba0 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
1bbb0 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
1bbc0 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
1bbd0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1bbe0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1bbf0 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
1bc00 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
1bc10 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
1bc20 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
1bc30 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1bc40 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
1bc50 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
1bc60 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
1bc70 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
1bc80 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
1bc90 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
1bca0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
1bcb0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1bcc0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1bcd0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1bce0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1bcf0 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
1bd00 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1bd10 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
1bd20 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
1bd30 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
1bd40 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
1bd50 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c  you should.** al
1bd60 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
1bd70 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
1bd80 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
1bd90 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
1bda0 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ral..**.** ^(The
1bdb0 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %Q option works
1bdc0 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20   like %q except 
1bdd0 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e  it also adds sin
1bde0 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e  gle quotes aroun
1bdf0 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65  d.** the outside
1be00 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74   of the total st
1be10 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61  ring.  Additiona
1be20 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61  lly, if the para
1be30 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20  meter in the.** 
1be40 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73  argument list is
1be50 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
1be60 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20   %Q substitutes 
1be70 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20  the text "NULL" 
1be80 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67  (without.** sing
1be90 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53  le quotes).)^  S
1bea0 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  o, for example, 
1beb0 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a  one could say:.*
1bec0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1bed0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1bee0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1bef0 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1bf00 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1bf10 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a  S(%Q)", zText);.
1bf20 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
1bf30 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
1bf40 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
1bf50 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
1bf60 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1bf70 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  te>.**.** The co
1bf80 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65  de above will re
1bf90 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53  nder a correct S
1bfa0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
1bfb0 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69  the zSQL.** vari
1bfc0 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65  able even if the
1bfd0 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20   zText variable 
1bfe0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1bff0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22  r..**.** ^(The "
1c000 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
1c010 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1c020 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74   "%s" but with t
1c030 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74  he.** addition t
1c040 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74  hat after the st
1c050 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65  ring has been re
1c060 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e  ad and copied in
1c070 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  to.** the result
1c080 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
1c090 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  )] is called on 
1c0a0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1c0b0 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c  .)^.*/.char *sql
1c0c0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e  ite3_mprintf(con
1c0d0 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63  st char*,...);.c
1c0e0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70  har *sqlite3_vmp
1c0f0 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
1c100 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61  *, va_list);.cha
1c110 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  r *sqlite3_snpri
1c120 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
1c130 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
1c140 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
1c150 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
1c160 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
1c170 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a  va_list);../*.**
1c180 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
1c190 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62  y Allocation Sub
1c1a0 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65  system.**.** The
1c1b0 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
1c1c0 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f  s these three ro
1c1d0 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f  utines for all o
1c1e0 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74  f its own.** int
1c1f0 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ernal memory all
1c200 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22  ocation needs. "
1c210 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65  Core" in the pre
1c220 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a  vious sentence.*
1c230 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  * does not inclu
1c240 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  de operating-sys
1c250 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53  tem specific VFS
1c260 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
1c270 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73    The.** Windows
1c280 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65   VFS uses native
1c290 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
1c2a0 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70  ee() for some op
1c2b0 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
1c2c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ^The sqlite3_mal
1c2d0 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65  loc() routine re
1c2e0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1c2f0 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66  to a block.** of
1c300 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74   memory at least
1c310 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67   N bytes in leng
1c320 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  th, where N is t
1c330 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
1c340 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
1c350 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20  loc() is unable 
1c360 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63  to obtain suffic
1c370 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d  ient free.** mem
1c380 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ory, it returns 
1c390 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1c3a0 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74   ^If the paramet
1c3b0 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  er N to.** sqlit
1c3c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a  e3_malloc() is z
1c3d0 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ero or negative 
1c3e0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c  then sqlite3_mal
1c3f0 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  loc() returns.**
1c400 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1c410 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1c420 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20  te3_malloc64(N) 
1c430 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75  routine works ju
1c440 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74  st like.** sqlit
1c450 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63  e3_malloc(N) exc
1c460 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e  ept that N is an
1c470 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74   unsigned 64-bit
1c480 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64   integer instead
1c490 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20  .** of a signed 
1c4a0 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a  32-bit integer..
1c4b0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
1c4c0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
1c4d0 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
1c4e0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
1c4f0 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
1c500 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1c510 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
1c520 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
1c530 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
1c540 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
1c550 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66    ^The sqlite3_f
1c560 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
1c570 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
1c580 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1c590 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
1c5a0 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
1c5b0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
1c5c0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
1c5d0 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
1c5e0 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
1c5f0 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
1c600 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
1c610 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
1c620 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
1c630 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
1c640 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
1c650 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
1c660 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
1c670 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
1c680 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
1c690 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
1c6a0 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
1c6b0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1c6c0 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
1c6d0 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
1c6e0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
1c6f0 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
1c700 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
1c710 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
1c720 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1c730 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1c740 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
1c750 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  ^The sqlite3_rea
1c760 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66  lloc(X,N) interf
1c770 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
1c780 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
1c790 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
1c7a0 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c  ion X to be at l
1c7b0 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a  east N bytes..**
1c7c0 20 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d   ^If the X param
1c7d0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1c7e0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20  realloc(X,N).** 
1c7f0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1c800 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
1c810 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
1c820 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
1c830 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1c840 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70  ..** ^If the N p
1c850 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1c860 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1c870 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
1c880 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
1c890 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
1c8a0 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
1c8b0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1c8c0 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20  te3_free(X)..** 
1c8d0 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  ^sqlite3_realloc
1c8e0 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20  (X,N) returns a 
1c8f0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
1c900 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
1c910 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  * of at least N 
1c920 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72  bytes in size or
1c930 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69   NULL if insuffi
1c940 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20  cient memory is 
1c950 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49  available..** ^I
1c960 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20  f M is the size 
1c970 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
1c980 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69  ocation, then mi
1c990 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20  n(N,M) bytes.** 
1c9a0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
1c9b0 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69  ocation are copi
1c9c0 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69  ed into the begi
1c9d0 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20  nning of buffer 
1c9e0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
1c9f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1ca00 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  ,N) and the prio
1ca10 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1ca20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71  freed..** ^If sq
1ca30 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1ca40 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  N) returns NULL 
1ca50 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76  and N is positiv
1ca60 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70  e, then the.** p
1ca70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1ca80 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a  is not freed..**
1ca90 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1caa0 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20  _realloc64(X,N) 
1cab0 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73  interfaces works
1cac0 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20   the same as.** 
1cad0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1cae0 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74  X,N) except that
1caf0 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75   N is a 64-bit u
1cb00 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
1cb10 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
1cb20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
1cb30 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  teger..**.** ^If
1cb40 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61   X is a memory a
1cb50 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f  llocation previo
1cb60 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
1cb70 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1cb80 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  c(),.** sqlite3_
1cb90 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69  malloc64(), sqli
1cba0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f  te3_realloc(), o
1cbb0 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1cbc0 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73  c64(), then.** s
1cbd0 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1cbe0 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65  returns the size
1cbf0 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20   of that memory 
1cc00 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79  allocation in by
1cc10 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  tes..** ^The val
1cc20 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
1cc30 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1cc40 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20  might be larger 
1cc50 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a  than the number.
1cc60 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75  ** of bytes requ
1cc70 65 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73  ested when X was
1cc80 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66   allocated.  ^If
1cc90 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   X is a NULL poi
1cca0 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  nter then.** sql
1ccb0 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65  ite3_msize(X) re
1ccc0 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20  turns zero.  If 
1ccd0 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65  X points to some
1cce0 74 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f  thing that is no
1ccf0 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69  t.** the beginni
1cd00 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  ng of memory all
1cd10 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69  ocation, or if i
1cd20 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f  t points to a fo
1cd30 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20  rmerly.** valid 
1cd40 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1cd50 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62  n that has now b
1cd60 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20  een freed, then 
1cd70 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
1cd80 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  of sqlite3_msize
1cd90 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  (X) is undefined
1cda0 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61   and possibly ha
1cdb0 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rmful..**.** ^Th
1cdc0 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
1cdd0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
1cde0 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  loc(), sqlite3_r
1cdf0 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c  ealloc(),.** sql
1ce00 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c  ite3_malloc64(),
1ce10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
1ce20 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61  lloc64().** is a
1ce30 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
1ce40 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
1ce50 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72  yte boundary, or
1ce60 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20   to a.** 4 byte 
1ce70 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20  boundary if the 
1ce80 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41  [SQLITE_4_BYTE_A
1ce90 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63  LIGNED_MALLOC] c
1cea0 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
1ceb0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
1cec0 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
1ced0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
1cee0 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
1cef0 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
1cf00 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
1cf10 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
1cf20 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
1cf30 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
1cf40 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
1cf50 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
1cf60 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
1cf70 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
1cf80 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
1cf90 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
1cfa0 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
1cfb0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1cfc0 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
1cfd0 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f  ..**.** Prior to
1cfe0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1cff0 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64  3.7.10, the Wind
1d000 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
1d010 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a   layer called.**
1d020 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
1d030 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1d040 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
1d050 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
1d060 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
1d070 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
1d080 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
1d090 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
1d0a0 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
1d0b0 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
1d0c0 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
1d0d0 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
1d0e0 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
1d0f0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77  ocation errors w
1d100 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75  ere detected, bu
1d110 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72  t.** they were r
1d120 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
1d130 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
1d140 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
1d150 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
1d160 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
1d170 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
1d180 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
1d190 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1d1a0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1d1b0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
1d1c0 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
1d1d0 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
1d1e0 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
1d1f0 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
1d200 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
1d210 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
1d220 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1d230 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
1d240 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
1d250 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
1d260 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
1d270 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
1d280 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
1d290 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
1d2a0 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
1d2b0 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
1d2c0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
1d2d0 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
1d2e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1d2f0 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  ]..*/.void *sqli
1d300 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
1d310 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d  .void *sqlite3_m
1d320 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f  alloc64(sqlite3_
1d330 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73  uint64);.void *s
1d340 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76  qlite3_realloc(v
1d350 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
1d360 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
1d370 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74  c64(void*, sqlit
1d380 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64  e3_uint64);.void
1d390 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
1d3a0 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69  id*);.sqlite3_ui
1d3b0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69  nt64 sqlite3_msi
1d3c0 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ze(void*);../*.*
1d3d0 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1d3e0 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
1d3f0 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51  tistics.**.** SQ
1d400 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
1d410 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
1d420 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
1d430 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
1d440 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
1d450 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
1d460 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
1d470 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1d480 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
1d490 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
1d4a0 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
1d4b0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
1d4c0 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  bsystem..**.** ^
1d4d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
1d4e0 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
1d4f0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
1d500 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
1d510 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  ** of memory cur
1d520 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
1d530 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
1d540 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20   not freed)..** 
1d550 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1d560 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1d570 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
1d580 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
1d590 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
1d5a0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1d5b0 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68  ] since the high
1d5c0 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77  -water mark.** w
1d5d0 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20  as last reset.  
1d5e0 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
1d5f0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1d600 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1d610 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1d620 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1d630 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
1d640 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65  overhead.** adde
1d650 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
1d660 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
1d670 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
1d680 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20  lloc()],.** but 
1d690 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
1d6a0 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
1d6b0 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
1d6c0 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69  library.** routi
1d6d0 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
1d6e0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
1d6f0 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  call..**.** ^The
1d700 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
1d710 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
1d720 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
1d730 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c  value of.** [sql
1d740 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1d750 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ()] if and only 
1d760 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1d770 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
1d780 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1d790 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54  ()] is true.  ^T
1d7a0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1d7b0 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
1d7c0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1d7d0 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
1d7e0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1d7f0 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
1d800 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  et..*/.sqlite3_i
1d810 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1d820 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
1d830 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
1d840 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1d850 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
1d860 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
1d870 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
1d880 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
1d890 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c  erator.**.** SQL
1d8a0 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68  ite contains a h
1d8b0 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
1d8c0 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72  do-random number
1d8d0 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47   generator (PRNG
1d8e0 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c  ) used to.** sel
1d8f0 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49  ect random [ROWI
1d900 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e  D | ROWIDs] when
1d910 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72   inserting new r
1d920 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61  ecords into a ta
1d930 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65  ble that.** alre
1d940 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72  ady uses the lar
1d950 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52  gest possible [R
1d960 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47  OWID].  The PRNG
1d970 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f   is also used fo
1d980 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69  r.** the build-i
1d990 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72  n random() and r
1d9a0 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20  andomblob() SQL 
1d9b0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73  functions.  This
1d9c0 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
1d9d0 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  s.** application
1d9e0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
1d9f0 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74  same PRNG for ot
1da00 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  her purposes..**
1da10 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74  .** ^A call to t
1da20 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
1da30 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
1da40 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
1da50 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20  ffer P..** ^The 
1da60 50 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20  P parameter can 
1da70 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
1da80 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69  r..**.** ^If thi
1da90 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f  s routine has no
1daa0 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c  t been previousl
1dab0 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74  y called or if t
1dac0 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63  he previous.** c
1dad0 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74  all had N less t
1dae0 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c  han one or a NUL
1daf0 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c  L pointer for P,
1db00 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69   then the PRNG i
1db10 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e  s.** seeded usin
1db20 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  g randomness obt
1db30 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78  ained from the x
1db40 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f  Randomness metho
1db50 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61  d of.** the defa
1db60 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
1db70 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66  ] object..** ^If
1db80 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
1db90 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
1dba0 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31  ne had an N of 1
1dbb0 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a   or more and a.*
1dbc0 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65  * non-NULL P the
1dbd0 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e  n the pseudo-ran
1dbe0 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72  domness is gener
1dbf0 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c  ated.** internal
1dc00 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72  ly and without r
1dc10 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b  ecourse to the [
1dc20 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61  sqlite3_vfs] xRa
1dc30 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68  ndomness.** meth
1dc40 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  od..*/.void sqli
1dc50 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
1dc60 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
1dc70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1dc80 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
1dc90 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
1dca0 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  backs.**.** ^Thi
1dcb0 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
1dcc0 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ers an authorize
1dcd0 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
1dce0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
1dcf0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1dd00 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20  tion], supplied 
1dd10 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
1dd20 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61  ument..** ^The a
1dd30 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1dd40 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
1dd50 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1dd60 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
1dd70 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
1dd80 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
1dd90 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
1dda0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1ddb0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1ddc0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e  _prepare16()] an
1ddd0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
1dde0 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74  re16_v2()].  ^At
1ddf0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e   various.** poin
1de00 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f  ts during the co
1de10 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73  mpilation proces
1de20 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62  s, as logic is b
1de30 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20  eing created.** 
1de40 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
1de50 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  us actions, the 
1de60 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1de70 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  ack is invoked t
1de80 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73  o.** see if thos
1de90 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  e actions are al
1dea0 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74  lowed.  ^The aut
1deb0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1dec0 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
1ded0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
1dee0 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
1def0 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
1df00 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
1df10 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
1df20 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
1df30 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1df40 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
1df50 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
1df60 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
1df70 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
1df80 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
1df90 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
1dfa0 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
1dfb0 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75  ror.  ^If the au
1dfc0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1dfd0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
1dfe0 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
1dff0 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
1e000 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
1e010 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
1e020 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
1e030 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1e040 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
1e050 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
1e060 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
1e070 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
1e080 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
1e090 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
1e0a0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1e0b0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1e0c0 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
1e0d0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
1e0e0 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
1e0f0 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61  k.  ^When the ca
1e100 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1e110 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
1e120 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
1e130 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
1e140 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
1e150 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
1e160 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
1e170 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
1e180 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
1e190 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
1e1a0 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
1e1b0 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ied. .**.** ^The
1e1c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1e1d0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1e1e0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
1e1f0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
1e200 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
1e210 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
1e220 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
1e230 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20  interface. ^The 
1e240 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1e250 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1e260 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
1e270 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
1e280 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
1e290 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
1e2a0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
1e2b0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
1e2c0 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69  orized. ^The thi
1e2d0 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
1e2e0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
1e2f0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
1e300 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
1e310 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
1e320 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e  contain addition
1e330 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62  al.** details ab
1e340 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
1e350 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
1e360 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
1e370 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
1e380 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
1e390 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
1e3a0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1e3b0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1e3c0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
1e3d0 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
1e3e0 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
1e3f0 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
1e400 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
1e410 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
1e420 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
1e430 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
1e440 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
1e450 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
1e460 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
1e470 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1e480 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
1e490 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
1e4a0 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
1e4b0 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
1e4c0 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
1e4d0 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20   of a table..** 
1e4e0 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
1e4f0 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  ode is [SQLITE_D
1e500 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63  ELETE] and the c
1e510 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
1e520 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ** [SQLITE_IGNOR
1e530 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c  E] then the [DEL
1e540 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70  ETE] operation p
1e550 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a  roceeds but the.
1e560 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  ** [truncate opt
1e570 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69  imization] is di
1e580 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72  sabled and all r
1e590 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
1e5a0 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a  individually..**
1e5b0 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
1e5c0 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b  r is used when [
1e5d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
1e5e0 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20  | preparing].** 
1e5f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
1e600 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
1e610 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
1e620 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
1e630 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f  statements.** do
1e640 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
1e650 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65  ss data they are
1e660 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
1e670 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
1e680 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20  y do not.** try 
1e690 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  to execute malic
1e6a0 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
1e6b0 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
1e6c0 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
1e6d0 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
1e6e0 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
1e6f0 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
1e700 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
1e710 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
1e720 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
1e730 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
1e740 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1e750 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
1e760 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
1e770 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
1e780 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
1e790 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
1e7a0 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
1e7b0 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
1e7c0 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
1e7d0 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
1e7e0 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
1e7f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
1e800 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
1e810 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f   that.** disallo
1e820 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78  ws everything ex
1e830 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74  cept [SELECT] st
1e840 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
1e850 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
1e860 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73  t need to proces
1e870 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75  s SQL from untru
1e880 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20  sted sources.** 
1e890 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69  might also consi
1e8a0 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73  der lowering res
1e8b0 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69  ource limits usi
1e8c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
1e8d0 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69  t()].** and limi
1e8e0 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69  ting database si
1e8f0 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61  ze using the [ma
1e900 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
1e910 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64  RAGMA].** in add
1e920 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61  ition to using a
1e930 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  n authorizer..**
1e940 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e  .** ^(Only a sin
1e950 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
1e960 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
1e970 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
1e980 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
1e990 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
1e9a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
1e9b0 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
1e9c0 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
1e9d0 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44  ious call.)^  ^D
1e9e0 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
1e9f0 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
1ea00 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
1ea10 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
1ea20 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
1ea30 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
1ea40 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
1ea50 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
1ea60 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
1ea70 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
1ea80 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
1ea90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1eaa0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
1eab0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1eac0 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
1ead0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1eae0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
1eaf0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
1eb00 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
1eb10 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1eb20 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
1eb30 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
1eb40 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
1eb50 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  raph..**.** ^Whe
1eb60 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
1eb70 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64  re_v2()] is used
1eb80 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74   to prepare a st
1eb90 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20  atement, the.** 
1eba0 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20  statement might 
1ebb0 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64  be re-prepared d
1ebc0 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
1ebd0 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
1ebe0 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
1ebf0 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
1ec00 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
1ec10 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
1ec20 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
1ec30 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ec40 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
1ec50 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
1ec60 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1ec70 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
1ec80 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1ec90 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1eca0 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
1ecb0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1ecc0 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
1ecd0 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
1ece0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
1ecf0 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
1ed00 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
1ed10 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
1ed20 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73  3_step()], unles
1ed30 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69  s.** as stated i
1ed40 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
1ed50 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65  aragraph, sqlite
1ed60 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73  3_step() invokes
1ed70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
1ed80 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72  are_v2() to repr
1ed90 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1eda0 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61  t after a schema
1edb0 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20   change..*/.int 
1edc0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1edd0 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
1ede0 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
1edf0 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
1ee00 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1ee10 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1ee20 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
1ee30 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
1ee40 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1ee50 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
1ee60 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
1ee70 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1ee80 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
1ee90 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1eea0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
1eeb0 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
1eec0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
1eed0 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
1eee0 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
1eef0 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
1ef00 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
1ef10 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
1ef20 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
1ef30 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
1ef40 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1ef50 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1ef60 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
1ef70 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
1ef80 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1ef90 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  n..**.** Note th
1efa0 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  at SQLITE_IGNORE
1efb0 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73   is also used as
1efc0 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73   a [conflict res
1efd0 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a  olution mode].**
1efe0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74   returned from t
1eff0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  he [sqlite3_vtab
1f000 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
1f010 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64  interface..*/.#d
1f020 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
1f030 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
1f040 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1f050 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
1f060 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f070 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
1f080 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
1f090 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
1f0a0 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
1f0b0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
1f0c0 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
1f0d0 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Action Codes.**.
1f0e0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1f0f0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1f100 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
1f110 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
1f120 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
1f130 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
1f140 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69  authorize certai
1f150 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1f160 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
1f170 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1f180 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
1f190 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
1f1a0 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
1f1b0 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
1f1c0 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
1f1d0 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
1f1e0 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
1f1f0 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
1f200 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
1f210 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
1f220 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
1f230 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
1f240 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
1f250 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
1f260 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
1f270 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e  e.** authorized.
1f280 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
1f290 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
1f2a0 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
1f2b0 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
1f2c0 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
1f2d0 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
1f2e0 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
1f2f0 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
1f300 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
1f310 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1f320 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35  ameter.  ^(The 5
1f330 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1f340 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
1f350 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
1f360 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
1f370 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
1f380 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29  "temp",.** etc.)
1f390 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29   if applicable.)
1f3a0 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61  ^  ^The 6th para
1f3b0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1f3c0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1f3d0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
1f3e0 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
1f3f0 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
1f400 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
1f410 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
1f420 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1f430 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
1f440 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
1f450 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
1f460 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
1f470 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   code..*/./*****
1f480 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f490 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f4a0 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
1f4b0 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
1f4c0 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
1f4d0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
1f4e0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
1f4f0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1f500 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1f510 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f520 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
1f530 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
1f540 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1f550 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f560 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f570 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1f580 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
1f590 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1f5a0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1f5b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f5c0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1f5d0 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
1f5e0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1f5f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f600 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f610 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1f620 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
1f630 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1f640 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f650 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f660 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
1f670 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
1f680 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1f690 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f6a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f6b0 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
1f6c0 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
1f6d0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1f6e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1f6f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f700 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
1f710 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
1f720 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1f730 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f740 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f750 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
1f760 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
1f770 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1f780 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f790 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1f7a0 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
1f7b0 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
1f7c0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1f7d0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1f7e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1f7f0 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
1f800 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
1f810 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1f820 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f830 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1f840 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
1f850 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
1f860 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1f870 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1f880 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1f890 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1f8a0 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
1f8b0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1f8c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f8d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1f8e0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
1f8f0 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
1f900 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1f910 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1f920 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1f930 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
1f940 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
1f950 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1f960 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f970 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
1f980 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
1f990 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1f9a0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1f9b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f9c0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
1f9d0 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
1f9e0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1f9f0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1fa00 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1fa10 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
1fa20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
1fa30 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1fa40 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1fa50 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1fa60 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
1fa70 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
1fa80 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
1fa90 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
1faa0 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
1fab0 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
1fac0 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
1fad0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1fae0 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
1faf0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1fb00 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
1fb10 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
1fb20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1fb30 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1fb40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1fb50 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
1fb60 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
1fb70 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
1fb80 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1fb90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1fba0 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
1fbb0 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
1fbc0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
1fbd0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
1fbe0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1fbf0 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
1fc00 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
1fc10 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
1fc20 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1fc30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fc40 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
1fc50 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
1fc60 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
1fc70 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1fc80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1fc90 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
1fca0 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
1fcb0 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
1fcc0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1fcd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
1fce0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
1fcf0 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
1fd00 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1fd10 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1fd20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
1fd30 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
1fd40 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
1fd50 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1fd60 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1fd70 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1fd80 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
1fd90 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
1fda0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
1fdb0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1fdc0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1fdd0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
1fde0 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
1fdf0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
1fe00 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1fe10 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
1fe20 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
1fe30 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
1fe40 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20         Function 
1fe50 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e  Name   */.#defin
1fe60 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49  e SQLITE_SAVEPOI
1fe70 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32  NT            32
1fe80 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
1fe90 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20        Savepoint 
1fea0 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65  Name  */.#define
1feb0 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
1fec0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
1fed0 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
1fee0 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  sed */.#define S
1fef0 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20  QLITE_RECURSIVE 
1ff00 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20             33   
1ff10 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1ff20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1ff30 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     */../*.** CAP
1ff40 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
1ff50 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
1ff60 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
1ff70 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
1ff80 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
1ff90 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
1ffa0 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
1ffb0 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
1ffc0 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
1ffd0 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
1ffe0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1fff0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
20000 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
20010 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
20020 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
20030 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
20040 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
20050 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
20060 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
20070 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
20080 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
20090 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
200a0 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
200b0 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
200c0 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
200d0 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
200e0 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
200f0 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
20100 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
20110 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
20120 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
20130 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
20140 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
20150 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
20160 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
20170 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
20180 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
20190 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
201a0 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
201b0 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
201c0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
201d0 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
201e0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
201f0 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
20200 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68  d to limit.** th
20210 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75  e length of [bou
20220 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78  nd parameter] ex
20230 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f  pansion in the o
20240 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33  utput of sqlite3
20250 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  _trace()..**.** 
20260 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
20270 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
20280 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
20290 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
202a0 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
202b0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
202c0 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
202d0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
202e0 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
202f0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
20300 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
20310 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
20320 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
20330 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
20340 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
20350 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
20360 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
20370 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
20380 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
20390 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
203a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
203b0 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
203c0 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
203d0 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
203e0 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
203f0 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
20400 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
20410 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
20420 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
20430 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
20440 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
20450 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
20460 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
20470 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a  callback.  The.*
20480 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  * sqlite3_profil
20490 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
204a0 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
204b0 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a  imental and is.*
204c0 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
204d0 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65  nge in future ve
204e0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
204f0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
20500 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
20510 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29  *, void(*xTrace)
20520 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
20530 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
20540 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
20550 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70   void *sqlite3_p
20560 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
20570 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
20580 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
20590 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
205a0 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
205b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
205c0 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
205d0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
205e0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  The sqlite3_prog
205f0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e  ress_handler(D,N
20600 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20  ,X,P) interface 
20610 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
20620 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
20630 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  X to be invoked 
20640 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
20650 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
20660 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
20670 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
20680 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
20690 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  and [sqlite3_get
206a0 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a  _table()] for.**
206b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
206c0 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d  tion D.  An exam
206d0 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
206e0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
206f0 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
20700 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
20710 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
20720 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  ** ^The paramete
20730 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68  r P is passed th
20740 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c  rough as the onl
20750 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  y parameter to t
20760 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  he .** callback 
20770 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68  function X.  ^Th
20780 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73  e parameter N is
20790 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65   the approximate
207a0 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b   number of .** [
207b0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
207c0 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68  instructions] th
207d0 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  at are evaluated
207e0 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73   between success
207f0 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ive.** invocatio
20800 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61  ns of the callba
20810 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20  ck X.  ^If N is 
20820 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68  less than one th
20830 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a  en the progress.
20840 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69  ** handler is di
20850 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  sabled..**.** ^O
20860 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f  nly a single pro
20870 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61  gress handler ma
20880 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20  y be defined at 
20890 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20  one time per.** 
208a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
208b0 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61  tion]; setting a
208c0 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61   new progress ha
208d0 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68  ndler cancels th
208e0 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e  e.** old one.  ^
208f0 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65  Setting paramete
20900 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61  r X to NULL disa
20910 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73  bles the progres
20920 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54  s handler..** ^T
20930 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
20940 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61  ler is also disa
20950 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20  bled by setting 
20960 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73  N to a value les
20970 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a  s.** than 1..**.
20980 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72  ** ^If the progr
20990 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
209a0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
209b0 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
209c0 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
209d0 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
209e0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
209f0 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
20a00 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
20a10 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69   GUI progress di
20a20 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
20a30 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
20a40 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  dler callback mu
20a50 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
20a60 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
20a70 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
20a80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
20a90 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
20aa0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
20ab0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
20ac0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20ad0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
20ae0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
20af0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
20b00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20b10 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
20b20 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
20b30 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
20b40 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73  ph..**.*/.void s
20b50 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
20b60 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
20b70 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
20b80 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
20b90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
20ba0 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
20bb0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
20bc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
20bd0 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
20be0 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
20bf0 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64  ile as specified
20c00 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65   by the .** file
20c10 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e  name argument. ^
20c20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
20c30 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
20c40 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
20c50 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
20c60 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
20c70 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
20c80 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
20c90 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
20ca0 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
20cb0 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64  open16(). ^(A [d
20cc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20cd0 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
20ce0 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
20cf0 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
20d00 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
20d10 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
20d20 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
20d30 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
20d40 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
20d50 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
20d60 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
20d70 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
20d80 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
20d90 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
20da0 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
20db0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
20dc0 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e  e3].** object.)^
20dd0 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61   ^(If the databa
20de0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
20df0 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
20e00 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
20e10 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
20e20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
20e30 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
20e40 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
20e50 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b  ned.)^ ^The.** [
20e60 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
20e70 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
20e80 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
20e90 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
20ea0 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
20eb0 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
20ec0 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
20ed0 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69  he error followi
20ee0 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20  ng a failure of 
20ef0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  any.** of the sq
20f00 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75  lite3_open() rou
20f10 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tines..**.** ^Th
20f20 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
20f30 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  ng will be UTF-8
20f40 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 63   for databases c
20f50 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
20f60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
20f70 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
20f80 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75  2().  ^The defau
20f90 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
20fa0 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65  databases.** cre
20fb0 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74  ated using sqlit
20fc0 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c  e3_open16() will
20fd0 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68   be UTF-16 in th
20fe0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
20ff0 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  der..**.** Wheth
21000 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
21010 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
21020 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
21030 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
21040 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
21050 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21060 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  on] handle shoul
21070 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
21080 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74  .** passing it t
21090 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
210a0 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
210b0 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
210c0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
210d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
210e0 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
210f0 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ike sqlite3_open
21100 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
21110 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f  t it accepts two
21120 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
21130 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
21140 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
21150 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
21160 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21170 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20  n.  ^(The flags 
21180 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
21190 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
211a0 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  ) can take one o
211b0 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
211c0 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
211d0 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
211e0 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
211f0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
21200 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
21210 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
21220 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  , [SQLITE_OPEN_S
21230 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20  HAREDCACHE],.** 
21240 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
21250 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f  VATECACHE], and/
21260 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
21270 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a  URI] flags:)^.**
21280 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64  .** <dl>.** ^(<d
21290 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
212a0 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a  EADONLY]</dt>.**
212b0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
212c0 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72  e is opened in r
212d0 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20  ead-only mode.  
212e0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
212f0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65  does not.** alre
21300 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  ady exist, an er
21310 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
21320 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
21330 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
21340 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e  _READWRITE]</dt>
21350 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
21360 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
21370 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
21380 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
21390 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a  le, or reading.*
213a0 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69  * only if the fi
213b0 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
213c0 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
213d0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
213e0 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73  In either.** cas
213f0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  e the database m
21400 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
21410 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  t, otherwise an 
21420 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
21430 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
21440 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
21450 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
21460 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
21470 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATE]</dt>.** <dd
21480 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
21490 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
214a0 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c  ing and writing,
214b0 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20   and is created 
214c0 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
214d0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
214e0 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68   This is the beh
214f0 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
21500 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a  ways used for.**
21510 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
21520 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
21530 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  16().</dd>)^.** 
21540 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  </dl>.**.** If t
21550 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
21560 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
21570 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  _v2() is not one
21580 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69   of the.** combi
21590 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
215a0 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  ove optionally c
215b0 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68  ombined with oth
215c0 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  er.** [SQLITE_OP
215d0 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51  EN_READONLY | SQ
215e0 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73  LITE_OPEN_* bits
215f0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ].** then the be
21600 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
21610 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
21620 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
21630 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  NOMUTEX] flag is
21640 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64   set, then the d
21650 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21660 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74  on.** opens in t
21670 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20  he multi-thread 
21680 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
21690 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
216a0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a  single-thread.**
216b0 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65   mode has not be
216c0 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  en set at compil
216d0 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
216e0 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a  time.  ^If the.*
216f0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  * [SQLITE_OPEN_F
21700 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  ULLMUTEX] flag i
21710 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64  s set then the d
21720 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21730 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74  on opens.** in t
21740 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
21750 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75  hreading mode] u
21760 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72  nless single-thr
21770 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  ead was.** previ
21780 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61  ously selected a
21790 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
217a0 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a  r start-time..**
217b0 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
217c0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20  EN_SHAREDCACHE] 
217d0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
217e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
217f0 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69  ion to be.** eli
21800 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68  gible to use [sh
21810 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
21820 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
21830 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
21840 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69  hared.** cache i
21850 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  s enabled using 
21860 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
21870 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e  shared_cache()].
21880 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54    ^The.** [SQLIT
21890 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
218a0 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
218b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
218c0 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a  nnection to not.
218d0 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69  ** participate i
218e0 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  n [shared cache 
218f0 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74  mode] even if it
21900 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
21910 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
21920 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
21930 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
21940 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
21950 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
21960 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
21970 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74  fines the operat
21980 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
21990 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  face that.** the
219a0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
219b0 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  nnection should 
219c0 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f  use.  ^If the fo
219d0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
219e0 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
219f0 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
21a00 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
21a10 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
21a20 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
21a30 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
21a40 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20  emory:", then a 
21a50 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
21a60 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ry in-memory dat
21a70 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61  abase.** is crea
21a80 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
21a90 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69  ection.  ^This i
21aa0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
21ab0 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68  e will vanish wh
21ac0 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  en.** the databa
21ad0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
21ae0 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
21af0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
21b00 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b  ite might.** mak
21b10 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
21b20 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
21b30 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e  names that begin
21b40 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
21b50 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69  aracter..** It i
21b60 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
21b70 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  at when a databa
21b80 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75  se filename actu
21b90 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
21ba0 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68  with.** a ":" ch
21bb0 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75  aracter you shou
21bc0 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ld prefix the fi
21bd0 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
21be0 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a  thname such as.*
21bf0 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20  * "./" to avoid 
21c00 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
21c10 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
21c20 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
21c30 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
21c40 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a  vate, temporary.
21c50 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  ** on-disk datab
21c60 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
21c70 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76  ted.  ^This priv
21c80 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
21c90 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
21ca0 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
21cb0 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
21cc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21cd0 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
21ce0 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
21cf0 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65  s in sqlite3_ope
21d00 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69  n()]] <h3>URI Fi
21d10 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  lenames</h3>.**.
21d20 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65  ** ^If [URI file
21d30 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61  name] interpreta
21d40 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c  tion is enabled,
21d50 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d   and the filenam
21d60 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65  e argument.** be
21d70 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a  gins with "file:
21d80 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65  ", then the file
21d90 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65  name is interpre
21da0 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55  ted as a URI. ^U
21db0 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  RI.** filename i
21dc0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
21dd0 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
21de0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
21df0 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74  ] flag is.** set
21e00 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61   in the fourth a
21e10 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
21e20 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72  e3_open_v2(), or
21e30 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65   if it has.** be
21e40 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61  en enabled globa
21e50 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53  lly using the [S
21e60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
21e70 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68  ] option with th
21e80 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
21e90 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f  nfig()] method o
21ea0 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  r by the [SQLITE
21eb0 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c  _USE_URI] compil
21ec0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
21ed0 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76  * As of SQLite v
21ee0 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52  ersion 3.7.7, UR
21ef0 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  I filename inter
21f00 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72  pretation is tur
21f10 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65  ned off.** by de
21f20 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72  fault, but futur
21f30 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
21f40 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c  Lite might enabl
21f50 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a  e URI filename.*
21f60 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  * interpretation
21f70 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65   by default.  Se
21f80 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  e "[URI filename
21f90 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  s]" for addition
21fa0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
21fb0 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c  n..**.** URI fil
21fc0 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65  enames are parse
21fd0 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52  d according to R
21fe0 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65  FC 3986. ^If the
21ff0 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e   URI contains an
22000 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74  .** authority, t
22010 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65  hen it must be e
22020 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73  ither an empty s
22030 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72  tring or the str
22040 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f  ing .** "localho
22050 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74  st". ^If the aut
22060 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e  hority is not an
22070 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
22080 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e   "localhost", an
22090 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65   .** error is re
220a0 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61  turned to the ca
220b0 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d  ller. ^The fragm
220c0 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ent component of
220d0 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70   a URI, if .** p
220e0 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72  resent, is ignor
220f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ed..**.** ^SQLit
22100 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20  e uses the path 
22110 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65  component of the
22120 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65   URI as the name
22130 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c   of the disk fil
22140 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61  e.** which conta
22150 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ins the database
22160 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62  . ^If the path b
22170 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27  egins with a '/'
22180 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20   character, .** 
22190 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72  then it is inter
221a0 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73  preted as an abs
221b0 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20  olute path. ^If 
221c0 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f  the path does no
221d0 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68  t begin .** with
221e0 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20   a '/' (meaning 
221f0 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
22200 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d  ty section is om
22210 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55  itted from the U
22220 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  RI).** then the 
22230 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65  path is interpre
22240 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76  ted as a relativ
22250 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e  e path. .** ^(On
22260 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69   windows, the fi
22270 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  rst component of
22280 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
22290 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65  h .** is a drive
222a0 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28   specification (
222b0 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a  e.g. "C:").)^.**
222c0 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71  .** [[core URI q
222d0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d  uery parameters]
222e0 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63  ].** The query c
222f0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
22300 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61  I may contain pa
22310 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72  rameters that ar
22320 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a  e interpreted.**
22330 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74   either by SQLit
22340 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20  e itself, or by 
22350 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20  a [VFS | custom 
22360 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
22370 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61  on]..** SQLite a
22380 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20  nd its built-in 
22390 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65  [VFSes] interpre
223a0 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  t the.** followi
223b0 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ng query paramet
223c0 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ers:.**.** <ul>.
223d0 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73  **   <li> <b>vfs
223e0 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22  </b>: ^The "vfs"
223f0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
22400 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66  e used to specif
22410 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a  y the name of.**
22420 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63       a VFS objec
22430 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20  t that provides 
22440 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
22450 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
22460 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20  hat should.**   
22470 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63    be used to acc
22480 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
22490 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e   file on disk. ^
224a0 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  If this option i
224b0 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20  s set to.**     
224c0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
224d0 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
224e0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20  object is used. 
224f0 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
22500 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46  nknown.**     VF
22510 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e  S is an error. ^
22520 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
22530 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
22540 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20   the vfs option 
22550 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e  is.**     presen
22560 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20  t, then the VFS 
22570 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
22580 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72   option takes pr
22590 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a  ecedence over.**
225a0 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70       the value p
225b0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75  assed as the fou
225c0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
225d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
225e0 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
225f0 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28   <b>mode</b>: ^(
22600 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  The mode paramet
22610 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
22620 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72   either "ro", "r
22630 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22  w",.**     "rwc"
22640 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41  , or "memory". A
22650 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74  ttempting to set
22660 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72   it to any other
22670 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20   value is.**    
22680 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a   an error)^. .**
22690 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73       ^If "ro" is
226a0 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e   specified, then
226b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
226c0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
226d0 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63  -only .**     ac
226e0 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66  cess, just as if
226f0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
22700 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67  N_READONLY] flag
22710 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e   had been set in
22720 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69   the .**     thi
22730 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
22740 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
22750 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f  . ^If the mode o
22760 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20  ption is set to 
22770 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68  .**     "rw", th
22780 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
22790 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
227a0 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f  ad-write (but no
227b0 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20  t create) .**   
227c0 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20    access, as if 
227d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
227e0 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53  WRITE (but not S
227f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
22800 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62  E) had .**     b
22810 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20  een set. ^Value 
22820 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c  "rwc" is equival
22830 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62  ent to setting b
22840 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49  oth .**     SQLI
22850 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
22860 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45  E and SQLITE_OPE
22870 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74  N_CREATE.  ^If t
22880 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
22890 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20  s.**     set to 
228a0 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20  "memory" then a 
228b0 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20  pure [in-memory 
228c0 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e  database] that n
228d0 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20  ever reads.**   
228e0 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d    or writes from
228f0 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e   disk is used. ^
22900 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74  It is an error t
22910 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75  o specify a valu
22920 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65  e for.**     the
22930 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
22940 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73  that is less res
22950 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68  trictive than th
22960 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a  at specified by.
22970 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73  **     the flags
22980 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74   passed in the t
22990 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
229a0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
229b0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
229c0 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20  > <b>cache</b>: 
229d0 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d  ^The cache param
229e0 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
229f0 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65  to either "share
22a00 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72  d" or.**     "pr
22a10 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67  ivate". ^Setting
22a20 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20   it to "shared" 
22a30 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
22a40 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20   setting the.** 
22a50 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
22a60 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20  SHAREDCACHE bit 
22a70 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  in the flags arg
22a80 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a  ument passed to.
22a90 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f  **     sqlite3_o
22aa0 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69  pen_v2(). ^Setti
22ab0 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72  ng the cache par
22ac0 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61  ameter to "priva
22ad0 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65  te" is .**     e
22ae0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
22af0 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  ting the SQLITE_
22b00 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
22b10 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49  E bit..**     ^I
22b20 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
22b30 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
22b40 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61  the "cache" para
22b50 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74  meter is present
22b60 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49   in.**     a URI
22b70 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76   filename, its v
22b80 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61  alue overrides a
22b90 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75  ny behavior requ
22ba0 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67  ested by setting
22bb0 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
22bc0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
22bd0 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   or SQLITE_OPEN_
22be0 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67  SHAREDCACHE flag
22bf0 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
22c00 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20  >psow</b>: ^The 
22c10 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69  psow parameter i
22c20 6e 64 69 63 61 74 65 73 20 77 68 65 74 68 65 72  ndicates whether
22c30 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20   or not the.**  
22c40 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76     [powersafe ov
22c50 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74  erwrite] propert
22c60 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e  y does or does n
22c70 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a  ot apply to the.
22c80 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d  **     storage m
22c90 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68  edia on which th
22ca0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
22cb0 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20  resides..**.**  
22cc0 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f  <li> <b>nolock</
22cd0 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20  b>: ^The nolock 
22ce0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
22cf0 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72  oolean query par
22d00 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68  ameter.**     wh
22d10 69 63 68 20 69 66 20 73 65 74 20 64 69 73 61 62  ich if set disab
22d20 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67  les file locking
22d30 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75   in rollback jou
22d40 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69  rnal modes.  Thi
22d50 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66  s.**     is usef
22d60 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67  ul for accessing
22d70 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61   a database on a
22d80 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74   filesystem that
22d90 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20   does not.**    
22da0 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67   support locking
22db0 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74  .  Caution:  Dat
22dc0 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
22dd0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
22de0 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d   two.**     or m
22df0 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20 77 72  ore processes wr
22e00 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20  ite to the same 
22e10 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79  database and any
22e20 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a   one of those.**
22e30 20 20 20 20 20 70 72 6f 63 65 73 73 65 73 20 75       processes u
22e40 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a  ses nolock=1..**
22e50 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d  .**  <li> <b>imm
22e60 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65  utable</b>: ^The
22e70 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d   immutable param
22e80 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61  eter is a boolea
22e90 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70  n query.**     p
22ea0 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e  arameter that in
22eb0 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65  dicates that the
22ec0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
22ed0 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20  s stored on.**  
22ee0 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64     read-only med
22ef0 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74  ia.  ^When immut
22f00 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c  able is set, SQL
22f10 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
22f20 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61   the.**     data
22f30 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74  base file cannot
22f40 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65   be changed, eve
22f50 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73 20 77  n by a process w
22f60 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20  ith higher.**   
22f70 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64    privilege, and
22f80 20 73 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   so the database
22f90 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d   is opened read-
22fa0 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63  only and all loc
22fb0 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20  king.**     and 
22fc0 63 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e  change detection
22fd0 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43   is disabled.  C
22fe0 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20  aution: Setting 
22ff0 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a  the immutable.**
23000 20 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e       property on
23010 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
23020 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61   that does in fa
23030 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65  ct change can re
23040 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69  sult.**     in i
23050 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79 20 72  ncorrect query r
23060 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53  esults and/or [S
23070 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65  QLITE_CORRUPT] e
23080 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65  rrors..**     Se
23090 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f  e also: [SQLITE_
230a0 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d  IOCAP_IMMUTABLE]
230b0 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c  ..**       .** <
230c0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63  /ul>.**.** ^Spec
230d0 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
230e0 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  n parameter in t
230f0 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
23100 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e  nt of a URI is n
23110 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20  ot an.** error. 
23120 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
23130 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
23140 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69   understand addi
23150 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20  tional query.** 
23160 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65  parameters.  See
23170 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74   "[query paramet
23180 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c  ers with special
23190 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69   meaning to SQLi
231a0 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69  te]" for.** addi
231b0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
231c0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  on..**.** [[URI 
231d0 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
231e0 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65  s]] <h3>URI file
231f0 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68  name examples</h
23200 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20  3>.**.** <table 
23210 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e  border="1" align
23220 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64  =center cellpadd
23230 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  ing=5>.** <tr><t
23240 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  h> URI filenames
23250 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a   <th> Results.**
23260 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
23270 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
23280 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
23290 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
232a0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
232b0 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74  directory..** <t
232c0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
232d0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62  e/fred/data.db<b
232e0 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  r>.**          f
232f0 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64  ile:///home/fred
23300 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a  /data.db <br> .*
23310 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
23320 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65  //localhost/home
23330 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
23340 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  r> <td> .**     
23350 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61       Open the da
23360 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f  tabase file "/ho
23370 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
23380 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
23390 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f  le://darkstar/ho
233a0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
233b0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
233c0 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72    An error. "dar
233d0 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20  kstar" is not a 
233e0 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f  recognized autho
233f0 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  rity..** <tr><td
23400 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70   style="white-sp
23410 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a  ace:nowrap"> .**
23420 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
23430 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32  //C:/Documents%2
23440 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f  0and%20Settings/
23450 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74  fred/Desktop/dat
23460 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e  a.db.**     <td>
23470 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f   Windows only: O
23480 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
23490 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73  ta.db" on fred's
234a0 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76   desktop on driv
234b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a  e.**          C:
234c0 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
234d0 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20  %20 escaping in 
234e0 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20  this example is 
234f0 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a  not strictly .**
23500 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73            necess
23510 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72  ary - space char
23520 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73  acters can be us
23530 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20  ed literally.** 
23540 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20           in URI 
23550 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74  filenames..** <t
23560 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
23570 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68  .db?mode=ro&cach
23580 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a  e=private <td> .
23590 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
235a0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
235b0 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
235c0 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61  irectory for rea
235d0 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a  d-only access..*
235e0 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72  *          Regar
235f0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
23600 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63   or not shared-c
23610 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61  ache mode is ena
23620 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  bled by.**      
23630 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65      default, use
23640 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65   a private cache
23650 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
23660 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
23670 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64  ta.db?vfs=unix-d
23680 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20  otfile <td>.**  
23690 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
236a0 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  e "/home/fred/da
236b0 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20  ta.db". Use the 
236c0 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69  special VFS "uni
236d0 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20  x-dotfile".**   
236e0 20 20 20 20 20 20 20 74 68 61 74 20 75 73 65 73         that uses
236f0 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c   dot-files in pl
23700 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76  ace of posix adv
23710 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a  isory locking..*
23720 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
23730 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61  data.db?mode=rea
23740 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20  donly <td> .**  
23750 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72          An error
23760 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20  . "readonly" is 
23770 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69  not a valid opti
23780 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65  on for the "mode
23790 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  " parameter..** 
237a0 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e  </table>.**.** ^
237b0 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20  URI hexadecimal 
237c0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
237d0 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f   (%HH) are suppo
237e0 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20  rted within the 
237f0 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72  path and.** quer
23800 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
23810 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63  a URI. A hexadec
23820 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
23830 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66  ence consists of
23840 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69   a.** percent si
23850 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f  gn - "%" - follo
23860 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74  wed by exactly t
23870 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  wo hexadecimal d
23880 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66  igits .** specif
23890 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61  ying an octet va
238a0 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65  lue. ^Before the
238b0 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63   path or query c
238c0 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a  omponents of a.*
238d0 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61  * URI filename a
238e0 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20  re interpreted, 
238f0 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64  they are encoded
23900 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64   using UTF-8 and
23910 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63   all .** hexadec
23920 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
23930 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62  ences replaced b
23940 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20  y a single byte 
23950 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a  containing the.*
23960 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  * corresponding 
23970 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70  octet. If this p
23980 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73  rocess generates
23990 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d   an invalid UTF-
239a0 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74  8 encoding,.** t
239b0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
239c0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
239d0 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
239e0 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  ws users:</b>  T
239f0 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  he encoding used
23a00 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d   for the filenam
23a10 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66  e argument.** of
23a20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
23a30 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
23a40 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54  _v2() must be UT
23a50 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65  F-8, not whateve
23a60 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73  r.** codepage is
23a70 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
23a80 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63  ed.  Filenames c
23a90 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e  ontaining intern
23aa0 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61  ational.** chara
23ab0 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f  cters must be co
23ac0 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38  nverted to UTF-8
23ad0 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e   prior to passin
23ae0 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73  g them into.** s
23af0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
23b00 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23b10 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ()..**.** <b>Not
23b20 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e  e to Windows Run
23b30 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20  time users:</b> 
23b40 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64   The temporary d
23b50 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65  irectory must be
23b60 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f   set.** prior to
23b70 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   calling sqlite3
23b80 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
23b90 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f  e3_open_v2().  O
23ba0 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75  therwise, variou
23bb0 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68  s.** features th
23bc0 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75  at require the u
23bd0 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20  se of temporary 
23be0 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a  files may fail..
23bf0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
23c00 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  [sqlite3_temp_di
23c10 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20  rectory].*/.int 
23c20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
23c30 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
23c40 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
23c50 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
23c60 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
23c70 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
23c80 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
23c90 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
23ca0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
23cb0 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
23cc0 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
23cd0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
23ce0 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
23cf0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
23d00 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
23d10 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
23d20 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
23d30 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
23d40 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
23d50 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
23d60 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
23d70 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
23d80 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
23d90 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
23da0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
23db0 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
23dc0 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
23dd0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
23de0 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
23df0 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
23e00 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
23e10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23e20 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20  : Obtain Values 
23e30 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65  For URI Paramete
23e40 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  rs.**.** These a
23e50 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69  re utility routi
23e60 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56  nes, useful to V
23e70 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
23e80 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a  ns, that check.*
23e90 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61  * to see if a da
23ea0 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20  tabase file was 
23eb0 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61  a URI that conta
23ec0 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20  ined a specific 
23ed0 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65  query .** parame
23ee0 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f  ter, and if so o
23ef0 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65  btains the value
23f00 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70   of that query p
23f10 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
23f20 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61  If F is the data
23f30 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f  base filename po
23f40 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74  inter passed int
23f50 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65  o the xOpen() me
23f60 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46  thod of .** a VF
23f70 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
23f80 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20   when the flags 
23f90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
23fa0 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20  en() has one or 
23fb0 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20  .** more of the 
23fc0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
23fd0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ] or [SQLITE_OPE
23fe0 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20  N_MAIN_DB] bits 
23ff0 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20  set and.** P is 
24000 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
24010 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c  query parameter,
24020 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
24030 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
24040 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  ,P) returns the 
24050 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a  value of the P.*
24060 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69  * parameter if i
24070 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55  t exists or a NU
24080 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20  LL pointer if P 
24090 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20  does not appear 
240a0 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70  as a .** query p
240b0 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20  arameter on F.  
240c0 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20  If P is a query 
240d0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a  parameter of F.*
240e0 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69  * has no explici
240f0 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71  t value, then sq
24100 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
24110 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
24120 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
24130 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
24140 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
24150 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
24160 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61  F,P,B) routine a
24170 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73  ssumes that P is
24180 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61   a boolean.** pa
24190 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
241a0 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20  rns true (1) or 
241b0 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64  false (0) accord
241c0 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ing to the value
241d0 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73  .** of P.  The s
241e0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
241f0 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
24200 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
24210 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c  1) if the.** val
24220 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61  ue of query para
24230 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
24240 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c  f "yes", "true",
24250 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a   or "on" in any.
24260 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68  ** case or if th
24270 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
24280 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e  ith a non-zero n
24290 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20  umber.  The .** 
242a0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
242b0 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
242c0 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73  nes returns fals
242d0 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c  e (0) if the val
242e0 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70  ue of.** query p
242f0 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
24300 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73  e of "no", "fals
24310 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20  e", or "off" in 
24320 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69  any case or.** i
24330 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
24340 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69  ns with a numeri
24350 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73  c zero.  If P is
24360 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20   not a query.** 
24370 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f  parameter on F o
24380 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  r if the value o
24390 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20  f P is does not 
243a0 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65  match any of the
243b0 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20  .** above, then 
243c0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
243d0 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
243e0 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a  ns (B!=0)..**.**
243f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
24400 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f  _int64(F,P,D) ro
24410 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74  utine converts t
24420 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e  he value of P in
24430 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73  to a.** 64-bit s
24440 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
24450 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69  d returns that i
24460 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20  nteger, or D if 
24470 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78  P does not.** ex
24480 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c  ist.  If the val
24490 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74  ue of P is somet
244a0 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
244b0 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e  an integer, then
244c0 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75  .** zero is retu
244d0 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20  rned..** .** If 
244e0 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  F is a NULL poin
244f0 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ter, then sqlite
24500 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
24510 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  F,P) returns NUL
24520 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  L and.** sqlite3
24530 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
24540 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20  ,B) returns B.  
24550 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55  If F is not a NU
24560 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a  LL pointer and.*
24570 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  * is not a datab
24580 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  ase file pathnam
24590 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53  e pointer that S
245a0 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74  QLite passed int
245b0 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56  o the xOpen.** V
245c0 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  FS method, then 
245d0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
245e0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
245f0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
24600 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69  obably.** undesi
24610 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  rable..*/.const 
24620 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72  char *sqlite3_ur
24630 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73  i_parameter(cons
24640 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
24650 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
24660 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69  Param);.int sqli
24670 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
24680 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
24690 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
246a0 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61  Param, int bDefa
246b0 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ult);.sqlite3_in
246c0 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  t64 sqlite3_uri_
246d0 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72  int64(const char
246e0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
246f0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
24700 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24710 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
24720 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a  d Messages.**.**
24730 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
24740 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63  rcode() interfac
24750 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
24760 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
24770 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
24780 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
24790 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
247a0 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69  cent failed sqli
247b0 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a  te3_* API call.*
247c0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
247d0 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
247e0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20  nnection]. If a 
247f0 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66  prior API call f
24800 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65  ailed.** but the
24810 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
24820 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c   call succeeded,
24830 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
24840 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  e from.** sqlite
24850 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
24860 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  ndefined.  ^The 
24870 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
24880 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
24890 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
248a0 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
248b0 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
248c0 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
248d0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
248e0 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
248f0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
24900 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
24910 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
24920 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
24930 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
24940 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
24950 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
24960 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
24970 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
24980 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
24990 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
249a0 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
249b0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
249c0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
249d0 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
249e0 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
249f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
24a00 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
24a10 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
24a20 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
24a30 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
24a40 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
24a50 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
24a60 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
24a70 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
24a80 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
24a90 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
24aa0 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
24ab0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
24ac0 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66  _errstr() interf
24ad0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
24ae0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
24af0 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65   text.** that de
24b00 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73  scribes the [res
24b10 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54  ult code], as UT
24b20 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  F-8..** ^(Memory
24b30 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
24b40 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
24b50 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
24b60 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d  ernally.** and m
24b70 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64  ust not be freed
24b80 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
24b90 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ion)^..**.** Whe
24ba0 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
24bb0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
24bc0 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
24bd0 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
24be0 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
24bf0 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
24c00 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
24c10 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
24c20 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
24c30 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
24c40 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
24c50 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
24c60 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
24c70 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
24c80 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
24c90 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
24ca0 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
24cb0 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
24cc0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
24cd0 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
24ce0 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
24cf0 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
24d00 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
24d10 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
24d20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
24d30 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
24d40 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
24d50 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
24d60 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
24d70 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
24d80 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
24d90 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
24da0 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
24db0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
24dc0 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
24dd0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
24de0 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
24df0 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
24e00 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
24e10 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
24e20 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
24e30 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
24e40 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
24e50 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
24e60 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
24e70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
24e80 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
24e90 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
24ea0 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
24eb0 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
24ec0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
24ed0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
24ee0 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  b);.int sqlite3_
24ef0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
24f00 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63  (sqlite3 *db);.c
24f10 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
24f20 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
24f30 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  3*);.const void 
24f40 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
24f50 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  6(sqlite3*);.con
24f60 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
24f70 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f  _errstr(int);../
24f80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
24f90 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
24fa0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
24fb0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
24fc0 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
24fd0 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
24fe0 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
24ff0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
25000 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
25010 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
25020 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
25030 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
25040 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
25050 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
25060 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
25070 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
25080 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
25090 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
250a0 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
250b0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
250c0 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
250d0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
250e0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
250f0 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
25100 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
25110 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
25120 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
25130 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
25140 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
25150 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
25160 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
25170 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
25180 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
25190 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
251a0 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
251b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
251c0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
251d0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
251e0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
251f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
25200 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
25210 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
25220 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
25230 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
25240 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
25250 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
25260 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
25270 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
25280 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
25290 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
252a0 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
252b0 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
252c0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
252d0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
252e0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
252f0 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
25300 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
25310 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
25320 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a  ime Limits.**.**
25330 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
25340 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
25350 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
25360 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
25370 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
25380 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
25390 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
253a0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
253b0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
253c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
253d0 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
253e0 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
253f0 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
25400 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
25410 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
25420 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
25430 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
25440 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
25450 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
25460 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
25470 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
25480 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
25490 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
254a0 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
254b0 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
254c0 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
254d0 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
254e0 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
254f0 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
25500 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
25510 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
25520 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
25530 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
25540 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
25550 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
25560 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
25570 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
25580 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
25590 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
255a0 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
255b0 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
255c0 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
255d0 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
255e0 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
255f0 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
25600 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
25610 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
25620 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
25630 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
25640 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
25650 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
25660 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
25670 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
25680 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
25690 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
256a0 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
256b0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
256c0 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
256d0 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
256e0 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
256f0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
25700 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
25710 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
25720 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
25730 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
25740 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
25750 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
25760 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
25770 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
25780 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
25790 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
257a0 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
257b0 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
257c0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
257d0 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
257e0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
257f0 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
25800 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
25810 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
25820 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
25830 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
25840 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
25850 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
25860 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
25870 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
25880 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
25890 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
258a0 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
258b0 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
258c0 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
258d0 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
258e0 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
258f0 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
25900 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
25910 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
25920 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
25930 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
25940 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
25950 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
25960 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
25970 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
25980 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
25990 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
259a0 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
259b0 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
259c0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
259d0 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
259e0 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
259f0 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
25a00 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
25a10 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
25a20 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
25a30 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
25a40 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
25a50 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
25a60 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
25a70 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
25a80 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
25a90 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
25aa0 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
25ab0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
25ac0 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ses..*/.int sqli
25ad0 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
25ae0 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
25af0 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
25b00 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
25b10 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
25b20 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
25b30 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
25b40 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
25b50 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
25b60 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
25b70 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
25b80 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
25b90 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
25ba0 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
25bb0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
25bc0 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
25bd0 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
25be0 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
25bf0 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
25c00 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
25c10 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
25c20 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
25c30 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
25c40 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
25c50 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
25c60 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  >.** [[SQLITE_LI
25c70 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  MIT_LENGTH]] ^(<
25c80 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
25c90 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
25ca0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
25cb0 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
25cc0 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
25cd0 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73  le row, in bytes
25ce0 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  .<dd>)^.**.** [[
25cf0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
25d00 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
25d10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
25d20 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
25d30 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
25d40 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
25d50 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
25d60 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
25d70 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
25d80 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74  T_COLUMN]] ^(<dt
25d90 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
25da0 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
25db0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
25dc0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
25dd0 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
25de0 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
25df0 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
25e00 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
25e10 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
25e20 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
25e30 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
25e40 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
25e50 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
25e60 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
25e70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
25e80 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
25e90 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
25ea0 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
25eb0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
25ec0 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
25ed0 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
25ee0 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29  xpression.</dd>)
25ef0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
25f00 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
25f10 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53  SELECT]] ^(<dt>S
25f20 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
25f30 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
25f40 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
25f50 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
25f60 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
25f70 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
25f80 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
25f90 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
25fa0 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e  VDBE_OP]] ^(<dt>
25fb0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
25fc0 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
25fd0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
25fe0 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
25ff0 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
26000 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
26010 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
26020 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
26030 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69  tement.  This li
26040 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65  mit is not curre
26050 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64  ntly.** enforced
26060 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69  , though that mi
26070 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20  ght be added in 
26080 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
26090 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
260a0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
260b0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
260c0 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c  NCTION_ARG]] ^(<
260d0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
260e0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74  FUNCTION_ARG</dt
260f0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
26100 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
26110 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75  rguments on a fu
26120 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  nction.</dd>)^.*
26130 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
26140 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e  MIT_ATTACHED]] ^
26150 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
26160 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
26170 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
26180 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54  um number of [AT
26190 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20  TACH | attached 
261a0 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64  databases].)^</d
261b0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
261c0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
261d0 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a  TERN_LENGTH]].**
261e0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
261f0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
26200 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
26210 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
26220 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
26230 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
26240 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a  o the [LIKE] or.
26250 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  ** [GLOB] operat
26260 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ors.</dd>)^.**.*
26270 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
26280 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
26290 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
262a0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
262b0 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
262c0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
262d0 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66   index number of
262e0 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d   any [parameter]
262f0 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
26300 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ment.)^.**.** [[
26310 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
26320 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  GGER_DEPTH]] ^(<
26330 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26340 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64  TRIGGER_DEPTH</d
26350 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
26360 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72  ximum depth of r
26370 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69  ecursion for tri
26380 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ggers.</dd>)^.**
26390 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
263a0 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
263b0 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  S]] ^(<dt>SQLITE
263c0 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
263d0 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  READS</dt>.** <d
263e0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
263f0 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72  mber of auxiliar
26400 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73  y worker threads
26410 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a   that a single.*
26420 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
26430 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74  ement] may start
26440 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
26450 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
26460 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
26470 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26480 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
26490 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
264a0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
264b0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
264c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
264d0 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
264e0 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
264f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
26500 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
26510 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
26520 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
26530 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
26540 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
26550 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
26560 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
26570 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
26580 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
26590 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
265a0 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
265b0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
265c0 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
265d0 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
265e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
265f0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
26600 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
26610 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
26620 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
26630 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
26640 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
26650 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
26660 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
26670 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
26680 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
26690 41 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31  ADS           11
266a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
266b0 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
266c0 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
266d0 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
266e0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
266f0 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
26700 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
26710 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
26720 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
26730 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
26740 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
26750 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
26760 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
26770 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
26780 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
26790 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
267a0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
267b0 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
267c0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
267d0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
267e0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
267f0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
26800 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
26810 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
26820 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
26830 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
26840 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
26850 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
26860 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
26870 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
26880 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
26890 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
268a0 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
268b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
268c0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
268d0 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
268e0 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
268f0 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
26900 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
26910 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
26920 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
26930 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
26940 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
26950 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  t is less than z
26960 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
26970 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
26980 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
26990 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
269a0 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
269b0 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
269c0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
269d0 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73  number of  bytes
269e0 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
269f0 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73    ^When nByte is
26a00 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
26a10 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
26a20 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
26a30 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
26a40 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
26a50 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
26a60 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
26a70 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
26a80 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
26a90 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
26aa0 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
26ab0 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
26ac0 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
26ad0 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
26ae0 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
26af0 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
26b00 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
26b10 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
26b20 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
26b30 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
26b40 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
26b50 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
26b60 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
26b70 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
26b80 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73  minator bytes as
26b90 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69   this saves SQLi
26ba0 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74  te from having t
26bb0 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79  o.** make a copy
26bc0 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   of the input st
26bd0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ring..**.** ^If 
26be0 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
26bf0 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
26c00 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
26c10 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
26c20 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
26c30 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
26c40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
26c50 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
26c60 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
26c70 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
26c80 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
26c90 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
26ca0 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
26cb0 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
26cc0 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
26cd0 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
26ce0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
26cf0 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
26d00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26d10 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
26d20 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
26d30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
26d40 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
26d50 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
26d60 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
26d70 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
26d80 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
26d90 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
26da0 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
26db0 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
26dc0 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
26dd0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
26de0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
26df0 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
26e00 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
26e10 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
26e20 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
26e30 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
26e40 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
26e50 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
26e60 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
26e70 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
26e80 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
26e90 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
26ea0 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
26eb0 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
26ec0 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
26ed0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
26ee0 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
26ef0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
26f00 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
26f10 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
26f20 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
26f30 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
26f40 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
26f50 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
26f60 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
26f70 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
26f80 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
26f90 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
26fa0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
26fb0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
26fc0 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
26fd0 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
26fe0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
26ff0 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
27000 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
27010 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
27020 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
27030 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
27040 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
27050 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
27060 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
27070 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
27080 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
27090 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
270a0 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
270b0 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
270c0 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
270d0 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
270e0 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
270f0 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
27100 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
27110 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
27120 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
27130 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
27140 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
27150 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
27160 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
27170 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
27180 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
27190 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53  n. As many as [S
271a0 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41  QLITE_MAX_SCHEMA
271b0 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69  _RETRY].** retri
271c0 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65  es will occur be
271d0 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65  fore sqlite3_ste
271e0 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64  p() gives up and
271f0 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f   returns an erro
27200 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  r..** </li>.**.*
27210 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
27220 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
27230 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
27240 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
27250 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
27260 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
27270 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
27280 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
27290 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
272a0 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
272b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
272c0 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
272d0 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
272e0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
272f0 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
27300 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
27310 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
27320 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
27330 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
27340 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
27350 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
27360 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
27370 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
27380 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
27390 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
273a0 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
273b0 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
273c0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
273d0 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
273e0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
273f0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
27400 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
27410 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
27420 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
27430 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
27440 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
27450 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
27460 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
27470 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
27480 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
27490 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
274a0 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
274b0 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
274c0 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
274d0 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
274e0 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
274f0 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
27500 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
27510 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
27520 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
27530 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
27540 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
27550 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
27560 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
27570 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
27580 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
27590 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
275a0 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
275b0 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
275c0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
275d0 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
275e0 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
275f0 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
27600 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
27610 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
27620 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
27630 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
27640 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
27650 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
27660 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
27670 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
27680 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e  * </li>.** </ol>
27690 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
276a0 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
276b0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
276c0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
276d0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
276e0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
276f0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
27700 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
27710 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
27720 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
27730 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
27740 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
27750 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
27760 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
27770 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
27780 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
27790 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
277a0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
277b0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
277c0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
277d0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
277e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
277f0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
27800 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
27810 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
27820 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
27830 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
27840 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
27850 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
27860 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
27870 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
27880 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
27890 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
278a0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
278b0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
278c0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
278d0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
278e0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
278f0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
27900 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
27910 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
27920 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
27930 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
27940 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
27950 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
27960 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
27970 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
27980 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
27990 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
279a0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
279b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
279c0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
279d0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
279e0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
279f0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
27a00 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
27a10 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
27a20 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
27a30 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
27a40 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
27a50 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
27a60 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
27a70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73  repare16_v2(.  s
27a80 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
27a90 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
27aa0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
27ab0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
27ac0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
27ad0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
27ae0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
27af0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
27b00 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
27b10 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
27b20 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
27b30 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
27b40 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
27b50 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
27b60 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
27b70 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
27b80 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
27b90 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
27ba0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   zSql */.);../*.
27bb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74  ** CAPI3REF: Ret
27bc0 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e  rieving Statemen
27bd0 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  t SQL.**.** ^Thi
27be0 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
27bf0 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
27c00 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
27c10 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
27c20 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
27c30 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
27c40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27c50 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
27c60 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
27c70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
27c80 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
27c90 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
27ca0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
27cb0 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  2()]..*/.const c
27cc0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
27cd0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
27ce0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
27cf0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
27d00 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
27d10 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65  ement Writes The
27d20 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20   Database.**.** 
27d30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
27d40 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e  t_readonly(X) in
27d50 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27d60 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
27d70 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69  if.** and only i
27d80 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
27d90 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b  statement] X mak
27da0 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61  es no direct cha
27db0 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63  nges to.** the c
27dc0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
27dd0 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a  tabase file..**.
27de0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70  ** Note that [ap
27df0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
27e00 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
27e10 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20   or.** [virtual 
27e20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68  tables] might ch
27e30 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
27e40 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20  e indirectly as 
27e50 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20  a side effect.  
27e60 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
27e70 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  e, if an applica
27e80 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66  tion defines a f
27e90 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22  unction "eval()"
27ea0 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20   that .** calls 
27eb0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
27ec0 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f  , then the follo
27ed0 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  wing SQL stateme
27ee0 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e  nt would.** chan
27ef0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
27f00 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64  file through sid
27f10 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a  e-effects:.**.**
27f20 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
27f30 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20  e>.**    SELECT 
27f40 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f  eval('DELETE FRO
27f50 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a  M t1') FROM t2;.
27f60 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
27f70 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74  quote>.**.** But
27f80 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45   because the [SE
27f90 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
27fa0 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
27fb0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
27fc0 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73  e.** directly, s
27fd0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
27fe0 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69  only() would sti
27ff0 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29  ll return true.)
28000 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63  ^.**.** ^Transac
28010 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61  tion control sta
28020 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20  tements such as 
28030 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54  [BEGIN], [COMMIT
28040 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a  ], [ROLLBACK],.*
28050 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61  * [SAVEPOINT], a
28060 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75  nd [RELEASE] cau
28070 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  se sqlite3_stmt_
28080 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
28090 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69  turn true,.** si
280a0 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  nce the statemen
280b0 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f  ts themselves do
280c0 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f   not actually mo
280d0 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
280e0 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20  e but.** rather 
280f0 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65  they control the
28100 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20   timing of when 
28110 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73  other statements
28120 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20   modify the .** 
28130 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20  database.  ^The 
28140 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45  [ATTACH] and [DE
28150 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73  TACH] statements
28160 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73   also cause.** s
28170 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
28180 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
28190 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69   true since, whi
281a0 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65  le those stateme
281b0 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  nts.** change th
281c0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
281d0 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  of a database co
281e0 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64  nnection, they d
281f0 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63  o not make .** c
28200 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f  hanges to the co
28210 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
28220 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64  abase files on d
28230 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  isk..*/.int sqli
28240 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
28250 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  y(sqlite3_stmt *
28260 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
28270 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
28280 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64  ne If A Prepared
28290 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42   Statement Has B
282a0 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20  een Reset.**.** 
282b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
282c0 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66  t_busy(S) interf
282d0 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
282e0 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74   (non-zero) if t
282f0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
28300 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73  statement] S has
28310 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74   been stepped at
28320 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e   least once usin
28330 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  g .** [sqlite3_s
28340 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20  tep(S)] but has 
28350 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c  not run to compl
28360 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73  etion and/or has
28370 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65   not .** been re
28380 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  set using [sqlit
28390 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e  e3_reset(S)].  ^
283a0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
283b0 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65  _busy(S).** inte
283c0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61  rface returns fa
283d0 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55  lse if S is a NU
283e0 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20  LL pointer.  If 
283f0 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e  S is not a .** N
28400 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  ULL pointer and 
28410 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72  is not a pointer
28420 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65   to a valid [pre
28430 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28440 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e  .** object, then
28450 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
28460 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
28470 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
28480 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ble..**.** This 
28490 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
284a0 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61   used in combina
284b0 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65  tion [sqlite3_ne
284c0 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f  xt_stmt()].** to
284d0 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70   locate all prep
284e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20  ared statements 
284f0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
28500 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63  a database .** c
28510 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61  onnection that a
28520 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65  re in need of be
28530 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73  ing reset.  This
28540 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a   can be used,.**
28550 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e   for example, in
28560 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74   diagnostic rout
28570 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66  ines to search f
28580 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20  or prepared .** 
28590 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
285a0 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72  are holding a tr
285b0 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a  ansaction open..
285c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
285d0 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33  tmt_busy(sqlite3
285e0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
285f0 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
28600 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
28610 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  e Object.** KEYW
28620 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
28630 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
28640 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
28650 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
28660 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
28670 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
28680 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
28690 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
286a0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
286b0 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
286c0 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
286d0 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
286e0 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
286f0 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
28700 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65  .  ^Values store
28710 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
28720 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
28730 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
28740 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
28750 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
28760 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
28770 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
28780 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
28790 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
287a0 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
287b0 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
287c0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
287d0 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
287e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
287f0 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
28800 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
28810 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
28820 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
28830 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
28840 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
28850 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
28860 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
28870 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
28880 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
28890 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
288a0 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
288b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
288c0 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
288d0 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
288e0 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
288f0 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
28900 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
28910 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74  is held.  An int
28920 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
28930 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
28940 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
28950 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
28960 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
28970 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
28980 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
28990 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
289a0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
289b0 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
289c0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
289d0 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
289e0 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
289f0 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
28a00 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
28a10 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
28a20 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
28a30 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
28a40 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
28a50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
28a60 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
28a70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
28a80 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
28a90 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
28aa0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
28ab0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
28ac0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
28ad0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
28ae0 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
28af0 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
28b00 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
28b10 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
28b20 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
28b30 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
28b40 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
28b50 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
28b60 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
28b70 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
28b80 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
28b90 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
28ba0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
28bb0 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
28bc0 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
28bd0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
28be0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
28bf0 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
28c00 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
28c10 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
28c20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
28c30 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
28c40 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
28c50 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
28c60 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
28c70 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
28c80 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
28c90 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
28ca0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
28cb0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
28cc0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
28cd0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
28ce0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
28cf0 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
28d00 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
28d10 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
28d20 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
28d30 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
28d40 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
28d50 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
28d60 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
28d70 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
28d80 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
28d90 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
28da0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
28db0 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
28dc0 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
28dd0 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
28de0 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
28df0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  t.**.** The cont
28e00 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
28e10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
28e20 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
28e30 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
28e40 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
28e50 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20    ^A pointer to 
28e60 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
28e70 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20  xt object.** is 
28e80 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
28e90 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69  ameter to [appli
28ea0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
28eb0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
28ec0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
28ed0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
28ee0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
28ef0 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20  ation will pass 
28f00 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  this.** pointer 
28f10 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c  through into cal
28f20 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
28f30 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69  esult_int | sqli
28f40 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a  te3_result()],.*
28f50 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  * [sqlite3_aggre
28f60 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c  gate_context()],
28f70 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
28f80 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
28f90 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
28fa0 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74  andle()], [sqlit
28fb0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
28fc0 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71  ],.** and/or [sq
28fd0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
28fe0 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
28ff0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
29000 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
29010 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
29020 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e  CAPI3REF: Bindin
29030 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
29040 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a  ared Statements.
29050 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f  ** KEYWORDS: {ho
29060 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68  st parameter} {h
29070 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20  ost parameters} 
29080 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  {host parameter 
29090 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  name}.** KEYWORD
290a0 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  S: {SQL paramete
290b0 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  r} {SQL paramete
290c0 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62  rs} {parameter b
290d0 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28  inding}.**.** ^(
290e0 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  In the SQL state
290f0 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20  ment text input 
29100 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
29110 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
29120 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
29130 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
29140 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61  eplaced by a [pa
29150 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61  rameter] that ma
29160 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c  tches one of fol
29170 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61  lowing.** templa
29180 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  tes:.**.** <ul>.
29190 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
291a0 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
291b0 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
291c0 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
291d0 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
291e0 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74  * In the templat
291f0 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65  es above, NNN re
29200 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65  presents an inte
29210 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
29220 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e  and VVV represen
29230 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72  ts an alphanumer
29240 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e  ic identifier.)^
29250 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66    ^The values of
29260 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
29270 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
29280 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
29290 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
292a0 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
292b0 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
292c0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
292d0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
292e0 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
292f0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
29300 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
29310 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
29320 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61  routines is alwa
29330 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ys.** a pointer 
29340 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
29350 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
29360 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73  urned from.** [s
29370 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
29380 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  2()] or its vari
29390 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ants..**.** ^The
293a0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
293b0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
293c0 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
293d0 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
293e0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53   ^The leftmost S
293f0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  QL parameter has
29400 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
29410 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20   ^When the same 
29420 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72  named.** SQL par
29430 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
29440 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
29450 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
29460 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
29470 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
29480 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
29490 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
294a0 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66  .** ^The index f
294b0 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
294c0 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
294d0 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
294e0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
294f0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
29500 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
29510 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a  d.  ^The index.*
29520 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
29530 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
29540 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
29550 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d  ^The NNN value m
29560 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
29570 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65   and the [sqlite
29580 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61  3_limit()].** pa
29590 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f  rameter [SQLITE_
295a0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
295b0 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20  UMBER] (default 
295c0 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a  value: 999)..**.
295d0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  ** ^The third ar
295e0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
295f0 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
29600 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
29610 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
29620 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
29630 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20  te3_bind_text() 
29640 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
29650 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73  text16().** or s
29660 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
29670 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
29680 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f  nter then the fo
29690 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a  urth parameter.*
296a0 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64  * is ignored and
296b0 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20   the end result 
296c0 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73  is the same as s
296d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
296e0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ()..**.** ^(In t
296f0 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
29700 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
29710 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
29720 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
29730 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
29740 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
29750 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
29760 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
29770 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
29780 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
29790 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
297a0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
297b0 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74  ters.)^.** ^If t
297c0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
297d0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
297e0 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
297f0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
29800 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  6().** is negati
29810 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e  ve, then the len
29820 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
29830 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
29840 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
29850 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
29860 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20   terminator..** 
29870 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
29880 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
29890 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
298a0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
298b0 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72  .** the behavior
298c0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
298d0 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  * If a non-negat
298e0 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  ive fourth param
298f0 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64  eter is provided
29900 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
29910 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _text().** or sq
29920 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
29930 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  6() or sqlite3_b
29940 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65  ind_text64() the
29950 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65  n.** that parame
29960 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20  ter must be the 
29970 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77  byte offset.** w
29980 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
29990 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63  minator would oc
299a0 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65  cur assuming the
299b0 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c   string were NUL
299c0 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  .** terminated. 
299d0 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
299e0 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20  acters occur at 
299f0 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73  byte offsets les
29a00 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76  s than .** the v
29a10 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72  alue of the four
29a20 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65  th parameter the
29a30 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
29a40 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c  string value wil
29a50 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62  l.** contain emb
29a60 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65  edded NULs.  The
29a70 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
29a80 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67  ssions involving
29a90 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68   strings.** with
29aa0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
29ab0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
29ac0 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
29ad0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c  gument to the BL
29ae0 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69  OB and string bi
29af0 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  nding interfaces
29b00 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63  .** is a destruc
29b10 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
29b20 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
29b30 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
29b40 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
29b50 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
29b60 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
29b70 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f   is called.** to
29b80 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
29b90 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65  BLOB or string e
29ba0 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ven if the call 
29bb0 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c  to bind API fail
29bc0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  s..** ^If the fi
29bd0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
29be0 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
29bf0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
29c00 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
29c10 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
29c20 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
29c30 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
29c40 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
29c50 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
29c60 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
29c70 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
29c80 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
29c90 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
29ca0 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
29cb0 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
29cc0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
29cd0 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
29ce0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
29cf0 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
29d00 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
29d10 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
29d20 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61  .** ^The sixth a
29d30 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
29d40 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
29d50 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a   must be one of.
29d60 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ** [SQLITE_UTF8]
29d70 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  , [SQLITE_UTF16]
29d80 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
29d90 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  E], or [SQLITE_U
29da0 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70  TF16LE].** to sp
29db0 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69  ecify the encodi
29dc0 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69  ng of the text i
29dd0 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
29de0 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68  meter.  If.** th
29df0 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74  e sixth argument
29e00 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
29e10 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74  _text64() is not
29e20 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61   one of the.** a
29e30 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68  llowed values sh
29e40 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66  own above, or if
29e50 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
29e60 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a  ng is different.
29e70 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f  ** from the enco
29e80 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62  ding specified b
29e90 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61  y the sixth para
29ea0 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
29eb0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75  behavior.** is u
29ec0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
29ed0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
29ee0 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
29ef0 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
29f00 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
29f10 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
29f20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41  with zeroes.  ^A
29f30 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
29f40 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
29f50 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
29f60 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
29f70 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
29f80 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
29f90 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
29fa0 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
29fb0 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
29fc0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
29fd0 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
29fe0 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
29ff0 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
2a000 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
2a010 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
2a020 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
2a030 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65  utines..** ^A ne
2a040 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
2a050 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
2a060 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
2a070 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
2a080 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68  ** ^If any of th
2a090 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2a0a0 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
2a0b0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
2a0c0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f  LL pointer.** fo
2a0d0 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2a0e0 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69  statement] or wi
2a0f0 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74  th a prepared st
2a100 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63  atement for whic
2a110 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  h.** [sqlite3_st
2a120 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  ep()] has been c
2a130 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e  alled more recen
2a140 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65  tly than [sqlite
2a150 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74  3_reset()],.** t
2a160 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c  hen the call wil
2a170 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
2a180 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e  _MISUSE].  If an
2a190 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28  y sqlite3_bind_(
2a1a0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20  ).** routine is 
2a1b0 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72  passed a [prepar
2a1c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2a1d0 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  at has been fina
2a1e0 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65  lized, the.** re
2a1f0 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
2a200 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68  d and probably h
2a210 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42  armful..**.** ^B
2a220 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
2a230 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
2a240 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2a250 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e   routine..** ^Un
2a260 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
2a270 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
2a280 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
2a290 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2a2a0 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74  d_* routines ret
2a2b0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
2a2c0 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
2a2d0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
2a2e0 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65   if anything goe
2a2f0 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51  s wrong..** ^[SQ
2a300 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67  LITE_TOOBIG] mig
2a310 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69  ht be returned i
2a320 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20  f the size of a 
2a330 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a  string or BLOB.*
2a340 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73  * exceeds limits
2a350 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c   imposed by [sql
2a360 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
2a370 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
2a380 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  ]) or.** [SQLITE
2a390 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a  _MAX_LENGTH]..**
2a3a0 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d   ^[SQLITE_RANGE]
2a3b0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2a3c0 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
2a3d0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
2a3e0 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54   range.  ^[SQLIT
2a3f0 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
2a400 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
2a410 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65   fails..**.** Se
2a420 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2a430 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2a440 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
2a450 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2a460 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
2a470 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
2a480 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2a490 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
2a4a0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c  e3_bind_blob(sql
2a4b0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2a4c0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2a4d0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
2a4e0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
2a4f0 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71  3_bind_blob64(sq
2a500 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2a510 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73  , const void*, s
2a520 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20  qlite3_uint64,. 
2a530 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a540 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76         void(*)(v
2a550 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
2a560 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28  te3_bind_double(
2a570 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a580 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74  nt, double);.int
2a590 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
2a5a0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
2a5b0 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20   int, int);.int 
2a5c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
2a5d0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2a5e0 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69  , int, sqlite3_i
2a5f0 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74  nt64);.int sqlit
2a600 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
2a610 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
2a620 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2a630 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  nd_text(sqlite3_
2a640 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  stmt*,int,const 
2a650 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a  char*,int,void(*
2a660 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
2a670 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2a680 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2a690 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
2a6a0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
2a6b0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
2a6c0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2a6d0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2a6e0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
2a6f0 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
2a700 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
2a710 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
2a720 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69  (*)(void*), unsi
2a730 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69  gned char encodi
2a740 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ng);.int sqlite3
2a750 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
2a760 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2a770 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
2a780 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2a790 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
2a7a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a7b0 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
2a7c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2a7d0 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
2a7e0 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  meters.**.** ^Th
2a7f0 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
2a800 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
2a810 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
2a820 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
2a830 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
2a840 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
2a850 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2a860 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
2a870 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
2a880 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
2a890 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
2a8a0 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
2a8b0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
2a8c0 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
2a8d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2a8e0 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
2a8f0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
2a900 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
2a910 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
2a920 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
2a930 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
2a940 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
2a950 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
2a960 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
2a970 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
2a980 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
2a990 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
2a9a0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
2a9b0 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
2a9c0 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
2a9d0 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
2a9e0 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
2a9f0 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
2aa00 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
2aa10 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2aa20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2aa30 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2aa40 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2aa50 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2aa60 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
2aa70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2aa80 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2aa90 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
2aaa0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2aab0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2aac0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2aad0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
2aae0 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
2aaf0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2ab00 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2ab10 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
2ab20 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
2ab30 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
2ab40 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
2ab50 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
2ab60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ab70 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
2ab80 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
2ab90 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
2aba0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
2abb0 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
2abc0 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
2abd0 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
2abe0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
2abf0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
2ac00 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
2ac10 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
2ac20 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
2ac30 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
2ac40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
2ac50 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
2ac60 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
2ac70 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
2ac80 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
2ac90 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
2aca0 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
2acb0 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
2acc0 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
2acd0 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
2ace0 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
2acf0 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
2ad00 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
2ad10 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2ad20 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
2ad30 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
2ad40 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
2ad50 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
2ad60 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
2ad70 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
2ad80 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
2ad90 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
2ada0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
2adb0 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
2adc0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
2add0 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
2ade0 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
2adf0 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
2ae00 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
2ae10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2ae20 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
2ae30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2ae40 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2ae50 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2ae60 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2ae70 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2ae80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2ae90 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2aea0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2aeb0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2aec0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ndex()]..*/.cons
2aed0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2aee0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2aef0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2af00 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
2af10 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
2af20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
2af30 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
2af40 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
2af50 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
2af60 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
2af70 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
2af80 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
2af90 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
2afa0 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
2afb0 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
2afc0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
2afd0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2afe0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
2aff0 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
2b000 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
2b010 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
2b020 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
2b030 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
2b040 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
2b050 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
2b060 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
2b070 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
2b080 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
2b090 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
2b0a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b0b0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
2b0c0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2b0d0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2b0e0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2b0f0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2b100 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2b110 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2b120 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2b130 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2b140 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2b150 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2b160 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2b170 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2b180 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
2b190 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
2b1a0 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
2b1b0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
2b1c0 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
2b1d0 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
2b1e0 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
2b1f0 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
2b200 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
2b210 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2b220 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
2b230 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
2b240 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2b250 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
2b260 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
2b270 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
2b280 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
2b290 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
2b2a0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
2b2b0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2b2c0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
2b2d0 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
2b2e0 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52  ult Set.**.** ^R
2b2f0 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
2b300 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2b310 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
2b320 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
2b330 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b340 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75  ment]. ^This rou
2b350 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
2b360 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
2b370 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
2b380 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
2b390 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
2b3a0 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
2b3b0 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
2b3c0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  so: [sqlite3_dat
2b3d0 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  a_count()].*/.in
2b3e0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2b3f0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2b400 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2b410 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2b420 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
2b430 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
2b440 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2b450 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
2b460 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
2b470 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
2b480 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
2b490 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
2b4a0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
2b4b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
2b4c0 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
2b4d0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2b4e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
2b4f0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
2b500 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
2b510 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2b520 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
2b530 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2b540 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2b550 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
2b560 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
2b570 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2b580 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b590 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
2b5a0 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
2b5b0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
2b5c0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
2b5d0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
2b5e0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
2b5f0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
2b600 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
2b610 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
2b620 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
2b630 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
2b640 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
2b650 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b660 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
2b670 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
2b680 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2b690 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
2b6a0 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
2b6b0 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
2b6c0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
2b6d0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2b6e0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
2b6f0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
2b700 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
2b710 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
2b720 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2b730 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
2b740 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
2b750 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
2b760 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
2b770 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
2b780 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
2b790 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
2b7a0 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
2b7b0 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
2b7c0 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
2b7d0 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
2b7e0 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
2b7f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2b800 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2b810 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
2b820 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
2b830 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
2b840 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
2b850 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
2b860 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
2b870 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
2b880 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
2b890 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
2b8a0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
2b8b0 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
2b8c0 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
2b8d0 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
2b8e0 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
2b8f0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
2b900 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2b910 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2b920 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b930 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
2b940 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2b950 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
2b960 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
2b970 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b980 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
2b990 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
2b9a0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
2b9b0 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
2b9c0 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
2b9d0 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73  mine the databas
2b9e0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a  e, table, and.**
2b9f0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
2ba00 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e  at is the origin
2ba10 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72   of a particular
2ba20 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
2ba30 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74  n.** [SELECT] st
2ba40 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  atement..** ^The
2ba50 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
2ba60 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
2ba70 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
2ba80 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
2ba90 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72  ither a UTF-8 or
2baa0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
2bab0 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f   ^The _database_
2bac0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2bad0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
2bae0 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
2baf0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
2bb00 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
2bb10 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
2bb20 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
2bb30 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
2bb40 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72   name..** ^The r
2bb50 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2bb60 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
2bb70 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2bb80 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
2bb90 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
2bba0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2bbb0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
2bbc0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
2bbd0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
2bbe0 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
2bbf0 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
2bc00 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
2bc10 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
2bc20 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
2bc30 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
2bc40 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
2bc50 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
2bc60 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
2bc70 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
2bc80 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
2bc90 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
2bca0 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
2bcb0 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
2bcc0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
2bcd0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
2bce0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2bcf0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
2bd00 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
2bd10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2bd20 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
2bd30 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
2bd40 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
2bd50 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
2bd60 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
2bd70 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
2bd80 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
2bd90 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
2bda0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
2bdb0 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
2bdc0 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
2bdd0 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
2bde0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2bdf0 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
2be00 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
2be10 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
2be20 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
2be30 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
2be40 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
2be50 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
2be60 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2be70 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
2be80 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
2be90 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
2bea0 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
2beb0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
2bec0 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
2bed0 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
2bee0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
2bef0 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
2bf00 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
2bf10 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
2bf20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
2bf30 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
2bf40 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
2bf50 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
2bf60 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
2bf70 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
2bf80 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
2bf90 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
2bfa0 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
2bfb0 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
2bfc0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
2bfd0 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
2bfe0 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
2bff0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
2c000 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
2c010 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
2c020 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
2c030 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
2c040 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
2c050 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
2c060 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
2c070 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
2c080 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
2c090 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
2c0a0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
2c0b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2c0c0 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
2c0d0 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
2c0e0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2c0f0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
2c100 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
2c110 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
2c120 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
2c130 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2c140 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
2c150 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
2c160 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
2c170 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
2c180 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c190 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
2c1a0 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
2c1b0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
2c1c0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2c1d0 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
2c1e0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2c1f0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2c200 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2c210 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2c220 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2c230 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
2c240 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2c250 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
2c260 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2c270 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
2c280 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2c290 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2c2a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
2c2b0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2c2c0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2c2d0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2c2e0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
2c2f0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2c300 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2c310 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2c320 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
2c330 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2c340 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2c350 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
2c360 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
2c370 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
2c380 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
2c390 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
2c3a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2c3b0 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
2c3c0 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
2c3d0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
2c3e0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2c3f0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
2c400 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
2c410 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
2c420 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
2c430 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
2c440 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
2c450 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
2c460 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
2c470 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
2c480 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
2c490 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
2c4a0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
2c4b0 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
2c4c0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
2c4d0 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
2c4e0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
2c4f0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
2c500 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2c510 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
2c520 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
2c530 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
2c540 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
2c550 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
2c560 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
2c570 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
2c580 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
2c590 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
2c5a0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
2c5b0 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
2c5c0 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
2c5d0 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
2c5e0 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
2c5f0 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
2c600 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
2c610 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
2c620 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
2c630 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2c640 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
2c650 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
2c660 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
2c670 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
2c680 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
2c690 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
2c6a0 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
2c6b0 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
2c6c0 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
2c6d0 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
2c6e0 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
2c6f0 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
2c700 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
2c710 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
2c720 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
2c730 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
2c740 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
2c750 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
2c760 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
2c770 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
2c780 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
2c790 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
2c7a0 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
2c7b0 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
2c7c0 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
2c7d0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2c7e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2c7f0 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
2c800 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2c810 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2c820 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
2c830 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2c840 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2c850 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
2c860 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2c870 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
2c880 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c890 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
2c8a0 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
2c8b0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
2c8c0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2c8d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c8e0 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
2c8f0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
2c900 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
2c910 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2c920 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2c930 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
2c940 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
2c950 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
2c960 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
2c970 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
2c980 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
2c990 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
2c9a0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
2c9b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2c9c0 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
2c9d0 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
2c9e0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
2c9f0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
2ca00 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
2ca10 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
2ca20 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2ca30 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2ca40 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
2ca50 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
2ca60 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2ca70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2ca80 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2ca90 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
2caa0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
2cab0 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
2cac0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
2cad0 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
2cae0 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
2caf0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2cb00 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
2cb10 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
2cb20 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
2cb30 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
2cb40 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
2cb50 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
2cb60 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
2cb70 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
2cb80 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
2cb90 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
2cba0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
2cbb0 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
2cbc0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2cbd0 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
2cbe0 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
2cbf0 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
2cc00 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
2cc10 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2cc20 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
2cc30 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
2cc40 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2cc50 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
2cc60 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
2cc70 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
2cc80 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
2cc90 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
2cca0 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
2ccb0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
2ccc0 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
2ccd0 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
2cce0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
2ccf0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
2cd00 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
2cd10 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
2cd20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2cd30 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
2cd40 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
2cd50 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74  n an.** explicit
2cd60 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
2cd70 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
2cd80 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
2cd90 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
2cda0 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
2cdb0 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
2cdc0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2cdd0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
2cde0 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
2cdf0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
2ce00 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
2ce10 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
2ce20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
2ce30 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
2ce40 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
2ce50 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
2ce60 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2ce70 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
2ce80 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
2ce90 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2cea0 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
2ceb0 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
2cec0 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
2ced0 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
2cee0 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
2cef0 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
2cf00 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
2cf10 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
2cf20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
2cf30 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
2cf40 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
2cf50 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
2cf60 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
2cf70 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
2cf80 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
2cf90 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2cfa0 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
2cfb0 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
2cfc0 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
2cfd0 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
2cfe0 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
2cff0 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
2d000 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
2d010 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
2d020 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
2d030 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
2d040 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
2d050 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
2d060 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
2d070 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
2d080 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
2d090 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2d0a0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
2d0b0 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
2d0c0 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
2d0d0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
2d0e0 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
2d0f0 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
2d100 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
2d110 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
2d120 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
2d130 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
2d140 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
2d150 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2d160 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
2d170 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2d180 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
2d190 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
2d1a0 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
2d1b0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
2d1c0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
2d1d0 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
2d1e0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
2d1f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
2d200 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
2d210 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
2d220 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
2d230 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
2d240 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
2d250 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
2d260 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2d270 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
2d280 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
2d290 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2d2a0 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
2d2b0 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
2d2c0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
2d2d0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2d2e0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
2d2f0 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
2d300 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
2d310 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
2d320 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2d330 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
2d340 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
2d350 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
2d360 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
2d370 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
2d380 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
2d390 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
2d3a0 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
2d3b0 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  1, a call to.** 
2d3c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2d3d0 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61  ] was required a
2d3e0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
2d3f0 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
2d400 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74  thing.** other t
2d410 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
2d420 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
2d430 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
2d440 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
2d450 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
2d460 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72   to reset the pr
2d470 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d480 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
2d490 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75  te3_reset()] wou
2d4a0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ld result in an 
2d4b0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2d4c0 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73  return from.** s
2d4d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2d4e0 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f  But after versio
2d4f0 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69  n 3.6.23.1, sqli
2d500 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
2d510 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
2d520 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
2d530 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
2d540 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
2d550 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
2d560 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
2d570 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
2d580 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
2d590 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
2d5a0 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
2d5b0 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
2d5c0 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
2d5d0 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
2d5e0 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
2d5f0 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
2d600 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
2d610 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
2d620 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
2d630 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
2d640 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
2d650 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
2d660 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
2d670 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
2d680 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
2d690 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2d6a0 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
2d6b0 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
2d6c0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2d6d0 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
2d6e0 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
2d6f0 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
2d700 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
2d710 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2d720 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
2d730 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
2d740 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
2d750 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2d760 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2d770 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
2d780 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
2d790 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
2d7a0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
2d7b0 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
2d7c0 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
2d7d0 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
2d7e0 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
2d7f0 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
2d800 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
2d810 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
2d820 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
2d830 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
2d840 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
2d850 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
2d860 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
2d870 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2d880 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2d890 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
2d8a0 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
2d8b0 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
2d8c0 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
2d8d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2d8e0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
2d8f0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
2d900 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
2d910 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
2d920 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
2d930 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
2d940 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
2d950 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2d960 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2d970 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2d980 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
2d990 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2d9a0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
2d9b0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
2d9c0 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20  esult set.**.** 
2d9d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2d9e0 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
2d9f0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2da00 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2da10 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
2da20 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
2da30 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
2da40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2da50 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
2da60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2da70 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
2da80 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
2da90 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
2daa0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
2dab0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2dac0 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
2dad0 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
2dae0 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
2daf0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2db00 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
2db10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2db20 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
2db30 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
2db40 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
2db50 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e  LL pointer..** ^
2db60 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2db70 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
2db80 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74  e returns 0 if t
2db90 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
2dba0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2dbb0 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
2dbc0 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  d [SQLITE_DONE].
2dbd0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64    ^The sqlite3_d
2dbe0 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20  ata_count(P).** 
2dbf0 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d  will return non-
2dc00 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73  zero if previous
2dc10 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2dc20 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
2dc30 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  ned.** [SQLITE_R
2dc40 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74  OW], except in t
2dc50 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b  he case of the [
2dc60 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74  PRAGMA increment
2dc70 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68  al_vacuum].** wh
2dc80 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65  ere it always re
2dc90 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65  turns zero since
2dca0 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68   each step of th
2dcb0 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a  at multi-step.**
2dcc0 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20   pragma returns 
2dcd0 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74  0 columns of dat
2dce0 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  a..**.** See als
2dcf0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
2dd00 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  mn_count()].*/.i
2dd10 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
2dd20 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2dd30 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2dd40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
2dd50 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
2dd60 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2dd70 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
2dd80 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
2dd90 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
2dda0 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
2ddb0 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
2ddc0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2ddd0 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
2dde0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
2ddf0 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
2de00 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
2de10 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
2de20 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
2de30 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
2de40 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
2de50 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
2de60 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
2de70 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
2de80 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2de90 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
2dea0 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
2deb0 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
2dec0 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
2ded0 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
2dee0 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
2def0 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
2df00 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
2df10 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
2df20 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
2df30 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
2df40 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
2df50 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
2df60 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
2df70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
2df80 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
2df90 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
2dfa0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2dfb0 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
2dfc0 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
2dfd0 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
2dfe0 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
2dff0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
2e000 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
2e010 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
2e020 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
2e030 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
2e040 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e050 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
2e060 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
2e070 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
2e080 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2e090 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s}.**.** These r
2e0a0 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65  outines form the
2e0b0 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e   "result set" in
2e0c0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
2e0d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2e0e0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2e0f0 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
2e100 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
2e110 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
2e120 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
2e130 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
2e140 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
2e150 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
2e160 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
2e170 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2e180 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
2e190 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
2e1a0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
2e1b0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
2e1c0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2e1d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2e1e0 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
2e1f0 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
2e200 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2e210 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
2e220 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
2e230 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
2e240 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
2e250 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
2e260 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
2e270 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2e280 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
2e290 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
2e2a0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2e2b0 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
2e2c0 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
2e2d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2e2e0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
2e2f0 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
2e300 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
2e310 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
2e320 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
2e330 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
2e340 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
2e350 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
2e360 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
2e370 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
2e380 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
2e390 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
2e3a0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2e3b0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2e3c0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2e3d0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2e3e0 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
2e3f0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
2e400 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
2e410 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2e420 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
2e430 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
2e440 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
2e450 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
2e460 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
2e470 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2e480 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
2e490 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
2e4a0 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
2e4b0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
2e4c0 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
2e4d0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2e4e0 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
2e4f0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2e500 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
2e510 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2e520 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2e530 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2e540 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
2e550 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
2e560 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
2e570 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
2e580 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
2e590 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
2e5a0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2e5b0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2e5c0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2e5d0 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
2e5e0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
2e5f0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
2e600 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
2e610 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
2e620 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
2e630 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
2e640 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
2e650 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
2e660 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
2e670 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
2e680 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
2e690 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
2e6a0 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
2e6b0 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
2e6c0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
2e6d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e6e0 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
2e6f0 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
2e700 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
2e710 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
2e720 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
2e730 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
2e740 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
2e750 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
2e760 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2e770 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2e780 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
2e790 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
2e7a0 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
2e7b0 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
2e7c0 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
2e7d0 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
2e7e0 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
2e7f0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
2e800 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2e810 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
2e820 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
2e830 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
2e840 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
2e850 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2e860 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2e870 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
2e880 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
2e890 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2e8a0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
2e8b0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2e8c0 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
2e8d0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
2e8e0 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
2e8f0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
2e900 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2e910 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2e920 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
2e930 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
2e940 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2e950 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
2e960 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2e970 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
2e980 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
2e990 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2e9a0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
2e9b0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2e9c0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
2e9d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2e9e0 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
2e9f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2ea00 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
2ea10 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
2ea20 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
2ea30 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  r UTF-16 string 
2ea40 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2ea50 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2ea60 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
2ea70 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2ea80 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2ea90 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
2eaa0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2eab0 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  lt is a UTF-8 st
2eac0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2ead0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2eae0 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  6() converts.** 
2eaf0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
2eb00 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65  F-16 and then re
2eb10 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2eb20 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
2eb30 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2eb40 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
2eb50 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2eb60 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73  umn_bytes16() us
2eb70 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
2eb80 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
2eb90 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
2eba0 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72   to a UTF-16 str
2ebb0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
2ebc0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2ebd0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
2ebe0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2ebf0 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
2ec00 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2ec10 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2ec20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2ec30 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20  .** ^The values 
2ec40 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2ec50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2ec60 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  s()] and .** [sq
2ec70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ec80 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69  es16()] do not i
2ec90 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
2eca0 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74  terminators at t
2ecb0 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
2ecc0 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
2ecd0 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
2ece0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
2ecf0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2ed00 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b  n_bytes()] and [
2ed10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2ed20 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68  ytes16()] are th
2ed30 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
2ed40 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
2ed50 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
2ed60 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
2ed70 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
2ed80 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2ed90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2eda0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
2edb0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
2edc0 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
2edd0 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
2ede0 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
2edf0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
2ee00 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
2ee10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2ee20 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
2ee30 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20  ength BLOB is a 
2ee40 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2ee50 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  .** ^The object 
2ee60 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2ee70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2ee80 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
2ee90 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2eea0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2eeb0 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
2eec0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2eed0 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
2eee0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
2eef0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2ef00 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
2ef10 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2ef20 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
2ef30 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2ef40 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2ef50 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2ef60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2ef70 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
2ef80 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
2ef90 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
2efa0 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
2efb0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
2efc0 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
2efd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2efe0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
2eff0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2f000 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
2f010 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2f020 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
2f030 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
2f040 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
2f050 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
2f060 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72  propriate.  ^For
2f070 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
2f080 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
2f090 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
2f0a0 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
2f0b0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
2f0c0 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
2f0d0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
2f0e0 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
2f0f0 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
2f100 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
2f110 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
2f120 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
2f130 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
2f140 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
2f150 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
2f160 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2f170 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
2f180 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
2f190 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
2f1a0 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
2f1b0 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
2f1c0 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
2f1d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2f1e0 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
2f1f0 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
2f200 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
2f210 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2f220 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
2f230 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
2f240 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2f250 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2f260 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2f270 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2f280 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2f290 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2f2a0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2f2b0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2f2c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2f2d0 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
2f2e0 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
2f2f0 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
2f300 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
2f310 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2f320 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2f330 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2f340 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
2f350 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2f360 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
2f370 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
2f380 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
2f390 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2f3a0 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
2f3b0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2f3c0 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
2f3d0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2f3e0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2f3f0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
2f400 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
2f410 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2f420 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
2f430 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
2f440 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c  to BLOB.** <tr><
2f450 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
2f460 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2f470 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
2f480 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
2f490 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
2f4a0 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
2f4b0 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
2f4c0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2f4d0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2f4e0 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
2f4f0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2f500 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2f510 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2f520 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
2f530 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2f540 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2f550 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
2f560 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2f570 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
2f580 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
2f590 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
2f5a0 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
2f5b0 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
2f5c0 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54  quote>)^.**.** T
2f5d0 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d  he table above m
2f5e0 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74  akes reference t
2f5f0 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  o standard C lib
2f600 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61  rary functions a
2f610 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f  toi().** and ato
2f620 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65  f().  SQLite doe
2f630 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65  s not really use
2f640 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2f650 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a  .  It has its.**
2f660 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20   own equivalent 
2f670 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65  internal routine
2f680 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61  s.  The atoi() a
2f690 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20  nd atof() names 
2f6a0 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74  are.** used in t
2f6b0 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65  he table for bre
2f6c0 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65  vity and because
2f6d0 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69   they are famili
2f6e0 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20  ar to most.** C 
2f6f0 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a  programmers..**.
2f700 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
2f710 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
2f720 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
2f730 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
2f740 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
2f750 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f760 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
2f770 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
2f780 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
2f790 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2f7a0 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
2f7b0 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
2f7c0 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
2f7d0 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
2f7e0 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
2f7f0 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
2f800 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
2f810 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
2f820 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2f830 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
2f840 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f850 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
2f860 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f870 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
2f880 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
2f890 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
2f8a0 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
2f8b0 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
2f8c0 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
2f8d0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2f8e0 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
2f8f0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
2f900 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2f910 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2f920 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2f930 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
2f940 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
2f950 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
2f960 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
2f970 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
2f980 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2f990 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
2f9a0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2f9b0 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
2f9c0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2f9d0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
2f9e0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
2f9f0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
2fa00 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
2fa10 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
2fa20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  </ul>.**.** ^Con
2fa30 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
2fa40 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
2fa50 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
2fa60 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
2fa70 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
2fa80 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
2fa90 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
2faa0 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
2fab0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
2fac0 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
2fad0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72   prior pointer r
2fae0 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68  eferences will h
2faf0 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
2fb00 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
2fb10 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
2fb20 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
2fb30 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
2fb40 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
2fb50 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
2fb60 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
2fb70 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
2fb80 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
2fb90 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
2fba0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65  ..**.** The safe
2fbb0 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74  st and easiest t
2fbc0 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63  o remember polic
2fbd0 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
2fbe0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
2fbf0 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
2fc00 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
2fc10 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  *.** <ul>.**  <l
2fc20 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2fc30 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
2fc40 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2fc50 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
2fc60 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2fc70 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2fc80 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
2fc90 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2fca0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
2fcb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2fcc0 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
2fcd0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2fce0 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
2fcf0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
2fd00 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
2fd10 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
2fd20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2fd30 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  xt(),.** sqlite3
2fd40 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
2fd50 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2fd60 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
2fd70 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
2fd80 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  sult.** into the
2fd90 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c   desired format,
2fda0 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
2fdb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2fdc0 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  s() or.** sqlite
2fdd0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2fde0 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  () to find the s
2fdf0 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
2fe00 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
2fe10 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  alls.** to sqlit
2fe20 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2fe30 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2fe40 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
2fe50 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
2fe60 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2fe70 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20  6(), and do not 
2fe80 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
2fe90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2fea0 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c  16().** with cal
2feb0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2fec0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
2fed0 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72  .** ^The pointer
2fee0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
2fef0 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
2ff00 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
2ff10 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
2ff20 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
2ff30 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
2ff40 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2ff50 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
2ff60 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2ff70 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
2ff80 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61   ^The memory spa
2ff90 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
2ffa0 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
2ffb0 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
2ffc0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
2ffd0 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73   <b>not</b> pass
2ffe0 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
2fff0 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
30000 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30010 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
30020 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
30030 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
30040 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
30050 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d  **.** ^(If a mem
30060 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
30070 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
30080 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
30090 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
300a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
300b0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
300c0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
300d0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
300e0 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
300f0 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
30100 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
30110 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
30120 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
30130 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
30140 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
30150 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
30160 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
30170 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e  NOMEM].)^.*/.con
30180 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
30190 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
301a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
301b0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
301c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
301d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
301e0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
301f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
30200 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
30210 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
30220 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
30230 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
30240 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
30250 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
30260 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
30270 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
30280 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
30290 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
302a0 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
302b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
302c0 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
302d0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
302e0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
302f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
30300 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
30310 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
30320 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
30330 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
30340 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
30350 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
30360 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
30370 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ol);.sqlite3_val
30380 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
30390 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
303a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
303b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
303c0 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
303d0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
303e0 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54   Object.**.** ^T
303f0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
30400 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
30410 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
30420 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
30430 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
30440 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
30450 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
30460 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
30470 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
30480 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
30490 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
304a0 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
304b0 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
304c0 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
304d0 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
304e0 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
304f0 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
30500 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
30510 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
30520 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
30530 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
30540 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
30550 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
30560 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
30570 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
30580 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
30590 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
305a0 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
305b0 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
305c0 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
305d0 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
305e0 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
305f0 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
30600 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
30610 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
30620 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
30630 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
30640 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
30650 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
30660 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
30670 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
30680 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
30690 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
306a0 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
306b0 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
306c0 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
306d0 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
306e0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
306f0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
30700 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
30710 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
30720 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
30730 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
30740 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
30750 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
30760 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
30770 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
30780 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
30790 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
307a0 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
307b0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
307c0 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
307d0 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
307e0 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
307f0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
30800 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
30810 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
30820 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
30830 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
30840 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
30850 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
30860 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
30870 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
30880 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
30890 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
308a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
308b0 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
308c0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
308d0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
308e0 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69  3_reset() functi
308f0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
30900 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65  reset a [prepare
30910 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
30920 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69  object back to i
30930 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
30940 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65  , ready to be re
30950 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41  -executed..** ^A
30960 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
30970 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20   variables that 
30980 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64  had values bound
30990 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a   to them using.*
309a0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
309b0 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
309c0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d  e3_bind_*() API]
309d0 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61   retain their va
309e0 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71  lues..** Use [sq
309f0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
30a00 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74  ings()] to reset
30a10 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a   the bindings..*
30a20 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
30a30 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
30a40 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68  erface resets th
30a50 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
30a60 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b  ement] S.** back
30a70 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   to the beginnin
30a80 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d  g of its program
30a90 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
30aa0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
30ab0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
30ac0 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
30ad0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30ae0 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
30af0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
30b00 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a   [SQLITE_DONE],.
30b10 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65  ** or if [sqlite
30b20 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e  3_step(S)] has n
30b30 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e  ever before been
30b40 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a   called on S,.**
30b50 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
30b60 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
30b70 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
30b80 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
30b90 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
30ba0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
30bb0 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
30bc0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30bd0 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
30be0 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
30bf0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
30c00 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  )] returns an ap
30c10 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
30c20 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
30c30 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
30c40 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
30c50 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
30c60 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66  the values.** of
30c70 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69   any [sqlite3_bi
30c80 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73  nd_blob|bindings
30c90 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] on the [prepar
30ca0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
30cb0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
30cc0 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
30cd0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
30ce0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
30cf0 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
30d00 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  SQL Functions.**
30d10 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
30d20 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
30d30 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f  utines}.** KEYWO
30d40 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
30d50 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
30d60 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f  nction}.** KEYWO
30d70 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
30d80 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
30d90 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e  nctions}.**.** ^
30da0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
30db0 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
30dc0 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
30dd0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
30de0 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
30df0 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
30e00 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
30e10 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
30e20 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
30e30 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
30e40 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
30e50 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
30e60 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
30e70 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  s between.** the
30e80 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
30e90 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
30ea0 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a  g expected for.*
30eb0 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * the second par
30ec0 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65  ameter (the name
30ed0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
30ee0 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a   being created).
30ef0 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65  ** and the prese
30f00 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f  nce or absence o
30f10 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63  f a destructor c
30f20 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74  allback for.** t
30f30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
30f40 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ata pointer..**.
30f50 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
30f60 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
30f70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30f80 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
30f90 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
30fa0 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
30fb0 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
30fc0 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
30fd0 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
30fe0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
30ff0 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
31000 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
31010 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
31020 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
31030 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
31040 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
31050 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
31060 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
31070 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
31080 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
31090 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
310a0 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  redefined.  ^The
310b0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
310c0 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
310d0 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61  o 255 bytes in a
310e0 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73   UTF-8.** repres
310f0 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73  entation, exclus
31100 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d  ive of the zero-
31110 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f  terminator.  ^No
31120 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
31130 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  .** length limit
31140 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74   is in UTF-8 byt
31150 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65  es, not characte
31160 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79  rs nor UTF-16 by
31170 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61  tes.  .** ^Any a
31180 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
31190 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
311a0 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
311b0 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
311c0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
311d0 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
311e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
311f0 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
31200 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
31210 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
31220 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
31230 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
31240 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
31250 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
31260 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
31270 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
31280 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
31290 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
312a0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
312b0 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
312c0 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
312d0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
312e0 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
312f0 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
31300 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
31310 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
31320 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
31330 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
31340 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
31350 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
31360 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
31370 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
31380 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
31390 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
313a0 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
313b0 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
313c0 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
313d0 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
313e0 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70  ameters.  The ap
313f0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
31400 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65   set this parame
31410 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ter to.** [SQLIT
31420 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68  E_UTF16LE] if th
31430 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  e function imple
31440 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
31450 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  s .** [sqlite3_v
31460 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d  alue_text16le()]
31470 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72   on an input, or
31480 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
31490 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  ] if the.** impl
314a0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b  ementation invok
314b0 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  es [sqlite3_valu
314c0 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e  e_text16be()] on
314d0 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a   an input, or.**
314e0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20   [SQLITE_UTF16] 
314f0 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  if [sqlite3_valu
31500 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75  e_text16()] is u
31510 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  sed, or [SQLITE_
31520 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69  UTF8].** otherwi
31530 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53  se.  ^The same S
31540 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  QL function may 
31550 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75  be registered mu
31560 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69  ltiple times usi
31570 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20  ng.** different 
31580 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
31590 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64  ncodings, with d
315a0 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65  ifferent impleme
315b0 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20  ntations for.** 
315c0 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  each encoding..*
315d0 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  * ^When multiple
315e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
315f0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
31600 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
31610 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
31620 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
31630 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
31640 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
31650 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
31660 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  on..**.** ^The f
31670 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
31680 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62  may optionally b
31690 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c  e ORed with [SQL
316a0 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
316b0 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  C].** to signal 
316c0 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f  that the functio
316d0 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65  n will always re
316e0 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65  turn the same re
316f0 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68  sult given.** th
31700 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69  e same inputs wi
31710 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51  thin a single SQ
31720 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f  L statement.  Mo
31730 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  st SQL functions
31740 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e   are.** determin
31750 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c  istic.  The buil
31760 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20  t-in [random()] 
31770 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
31780 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a  an example of a.
31790 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ** function that
317a0 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e   is not determin
317b0 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69  istic.  The SQLi
317c0 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  te query planner
317d0 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70   is able to.** p
317e0 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61  erform additiona
317f0 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20  l optimizations 
31800 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  on deterministic
31810 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75   functions, so u
31820 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51  se.** of the [SQ
31830 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
31840 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f  IC] flag is reco
31850 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f  mmended where po
31860 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ssible..**.** ^(
31870 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
31880 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
31890 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
318a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
318b0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
318c0 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
318d0 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
318e0 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
318f0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
31900 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  )^.**.** ^The si
31910 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64  xth, seventh and
31920 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65   eighth paramete
31930 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
31940 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
31950 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
31960 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
31970 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
31980 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
31990 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
319a0 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20  gate. ^A scalar 
319b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
319c0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
319d0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
319e0 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
319f0 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e   only; NULL poin
31a00 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73  ters must be pas
31a10 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
31a20 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
31a30 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61  arameters. ^An a
31a40 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
31a50 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
31a60 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
31a70 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
31a80 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
31a90 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65   pointer must be
31aa0 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
31ab0 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e  c. ^To delete an
31ac0 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c   existing.** SQL
31ad0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
31ae0 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
31af0 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61  L pointers for a
31b00 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
31b10 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  n.** callbacks..
31b20 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e  **.** ^(If the n
31b30 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  inth parameter t
31b40 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
31b50 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69  _function_v2() i
31b60 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74  s not NULL,.** t
31b70 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75  hen it is destru
31b80 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  ctor for the app
31b90 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
31ba0 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64  inter. .** The d
31bb0 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76  estructor is inv
31bc0 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75  oked when the fu
31bd0 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
31be0 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69  d, either by bei
31bf0 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64  ng.** overloaded
31c00 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74   or when the dat
31c10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
31c20 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54   closes.)^.** ^T
31c30 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
31c40 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66   also invoked if
31c50 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
31c60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
31c70 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69  unction_v2() fai
31c80 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  ls..** ^When the
31c90 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
31ca0 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74  back of the tent
31cb0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  h parameter is i
31cc0 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73  nvoked, it.** is
31cd0 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65   passed a single
31ce0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
31cf0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
31d00 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
31d10 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68  a .** pointer wh
31d20 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74  ich was the fift
31d30 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
31d40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31d50 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  nction_v2()..**.
31d60 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74  ** ^It is permit
31d70 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
31d80 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
31d90 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
31da0 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
31db0 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
31dc0 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
31dd0 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
31de0 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
31df0 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
31e00 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
31e10 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e  xt encodings.  ^
31e20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
31e30 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
31e40 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20  ation that most 
31e50 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
31e60 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
31e70 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
31e80 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e  tion is used.  ^
31e90 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  A function imple
31ea0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
31eb0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a   non-negative.**
31ec0 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20   nArg parameter 
31ed0 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63  is a better matc
31ee0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
31ef0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
31f00 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74   with.** a negat
31f10 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75  ive nArg.  ^A fu
31f20 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
31f30 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
31f40 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
31f50 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
31f60 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
31f70 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
31f80 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
31f90 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
31fa0 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
31fb0 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e   .** ^A function
31fc0 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
31fd0 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
31fe0 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
31ff0 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
32000 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
32010 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
32020 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
32030 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
32040 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
32050 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
32060 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66  *.** ^Built-in f
32070 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
32080 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65  overloaded by ne
32090 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  w application-de
320a0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e  fined functions.
320b0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69  .**.** ^An appli
320c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
320d0 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
320e0 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
320f0 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
32100 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
32110 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
32120 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
32130 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
32140 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61  nection nor fina
32150 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
32160 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
32170 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
32180 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
32190 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74   running..*/.int
321a0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
321b0 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
321c0 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
321d0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
321e0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
321f0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
32200 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
32210 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
32220 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32230 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
32240 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
32250 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
32260 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
32270 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
32280 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
32290 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
322a0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
322b0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
322c0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
322d0 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
322e0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
322f0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
32300 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
32310 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
32320 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
32330 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
32340 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
32350 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
32360 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32370 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
32380 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
32390 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
323a0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
323b0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
323c0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73  function_v2(.  s
323d0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
323e0 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
323f0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
32400 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
32410 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
32420 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
32430 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
32440 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
32450 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
32460 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
32470 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
32480 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
32490 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
324a0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
324b0 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  t*),.  void(*xDe
324c0 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
324d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
324e0 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
324f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
32500 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
32510 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
32520 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
32530 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
32540 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
32550 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
32560 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
32570 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 20  TF8           1 
32580 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35     /* IMP: R-375
32590 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66  14-35566 */.#def
325a0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
325b0 4c 45 20 20 20 20 20 20 20 20 32 20 20 20 20 2f  LE        2    /
325c0 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33  * IMP: R-03371-3
325d0 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20  7637 */.#define 
325e0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
325f0 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d        3    /* IM
32600 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34  P: R-51971-34154
32610 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
32620 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
32630 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
32640 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
32650 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
32660 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
32670 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61   5    /* Depreca
32680 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ted */.#define S
32690 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
326a0 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c  NED  8    /* sql
326b0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
326c0 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  ation only */../
326d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
326e0 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a  unction Flags.**
326f0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
32700 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20  nts may be ORed 
32710 74 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68  together with th
32720 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  e .** [SQLITE_UT
32730 46 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74  F8 | preferred t
32740 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73  ext encoding] as
32750 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
32760 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ment.** to [sqli
32770 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32780 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
32790 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
327a0 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
327b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
327c0 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  ction_v2()]..*/.
327d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
327e0 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20  ETERMINISTIC    
327f0 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  0x800../*.** CAP
32800 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
32810 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
32820 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
32830 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
32840 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
32850 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
32860 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
32870 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
32880 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
32890 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
328a0 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
328b0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
328c0 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
328d0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
328e0 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
328f0 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
32900 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
32910 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
32920 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
32930 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
32940 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
32950 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
32960 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  ou what they do.
32970 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
32980 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
32990 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ED.SQLITE_DEPREC
329a0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
329b0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
329c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
329d0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
329e0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
329f0 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
32a00 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
32a10 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
32a20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
32a30 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
32a40 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
32a50 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
32a60 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
32a70 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
32a80 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
32a90 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
32aa0 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
32ab0 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
32ac0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
32ad0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
32ae0 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
32af0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
32b00 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20  e3_int64,int),. 
32b10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32b20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74       void*,sqlit
32b30 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69  e3_int64);.#endi
32b40 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
32b50 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
32b60 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65   Function Parame
32b70 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a  ter Values.**.**
32b80 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20   The C-language 
32b90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
32ba0 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  f SQL functions 
32bb0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75  and aggregates u
32bc0 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20  ses.** this set 
32bd0 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  of interface rou
32be0 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20  tines to access 
32bf0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61  the parameter va
32c00 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66  lues on.** the f
32c10 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
32c20 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gate..**.** The 
32c30 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61  xFunc (for scala
32c40 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20  r functions) or 
32c50 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65  xStep (for aggre
32c60 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72  gates) parameter
32c70 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
32c80 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32c90 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
32ca0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32cb0 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20  16()].** define 
32cc0 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69  callbacks that i
32cd0 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
32ce0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
32cf0 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68  ggregates..** Th
32d00 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
32d10 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63  to these callbac
32d20 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ks is an array o
32d30 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a  f pointers to.**
32d40 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
32d50 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
32d60 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e  ts.  There is on
32d70 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
32d80 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20  ] object for.** 
32d90 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74  each parameter t
32da0 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
32db0 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  on.  These routi
32dc0 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a  nes are used to.
32dd0 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65  ** extract value
32de0 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  s from the [sqli
32df0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
32e00 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ts..**.** These 
32e10 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e  routines work on
32e20 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74  ly with [protect
32e30 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32e40 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e  ] objects..** An
32e50 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  y attempt to use
32e60 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
32e70 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  on an [unprotect
32e80 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32e90 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75  ].** object resu
32ea0 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
32eb0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
32ec0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
32ed0 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20   work just like 
32ee0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
32ef0 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  g [column access
32f00 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65   functions].** e
32f10 78 63 65 70 74 20 74 68 61 74 20 74 68 65 73 65  xcept that these
32f20 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
32f30 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74   single [protect
32f40 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32f50 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e  ] object.** poin
32f60 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  ter instead of a
32f70 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
32f80 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20   pointer and an 
32f90 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e  integer column n
32fa0 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  umber..**.** ^Th
32fb0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
32fc0 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
32fd0 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
32fe0 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69  F-16 string.** i
32ff0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
33000 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68  e-order of the h
33010 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54  ost machine.  ^T
33020 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  he.** sqlite3_va
33030 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61  lue_text16be() a
33040 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nd sqlite3_value
33050 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65  _text16le() inte
33060 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63  rfaces.** extrac
33070 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73  t UTF-16 strings
33080 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61   as big-endian a
33090 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  nd little-endian
330a0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
330b0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
330c0 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
330d0 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
330e0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
330f0 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
33100 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
33110 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
33120 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
33130 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
33140 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
33150 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
33160 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
33170 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
33180 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
33190 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
331a0 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
331b0 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
331c0 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76   words, if the v
331d0 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67  alue is a string
331e0 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
331f0 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
33200 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  en the conversio
33210 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20  n is performed. 
33220 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
33230 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
33240 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
33250 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
33260 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
33270 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
33280 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65  .)^.**.** Please
33290 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20   pay particular 
332a0 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65  attention to the
332b0 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70   fact that the p
332c0 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a  ointer returned.
332d0 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
332e0 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20  _value_blob()], 
332f0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
33300 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  ext()], or.** [s
33310 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
33320 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e  t16()] can be in
33330 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73  validated by a s
33340 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
33350 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  o.** [sqlite3_va
33360 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73  lue_bytes()], [s
33370 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
33380 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  es16()], [sqlite
33390 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
333a0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
333b0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e  value_text16()].
333c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
333d0 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
333e0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
333f0 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20  me thread as.** 
33400 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
33410 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74   that supplied t
33420 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
33430 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  e*] parameters..
33440 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
33450 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
33460 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  b(sqlite3_value*
33470 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
33480 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
33490 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
334a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
334b0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
334c0 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71  lue*);.double sq
334d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
334e0 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
334f0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
33500 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
33510 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74  3_value*);.sqlit
33520 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
33530 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
33540 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
33550 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
33560 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
33570 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
33580 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
33590 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
335a0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
335b0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
335c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
335d0 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
335e0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
335f0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
33600 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
33610 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
33620 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
33630 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
33640 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
33650 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
33660 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ic_type(sqlite3_
33670 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
33680 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
33690 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
336a0 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  ion Context.**.*
336b0 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * Implementation
336c0 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53  s of aggregate S
336d0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  QL functions use
336e0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
336f0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
33700 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ory for storing 
33710 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a  their state..**.
33720 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
33730 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61  me the sqlite3_a
33740 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
33750 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73  (C,N) routine is
33760 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20   called .** for 
33770 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67  a particular agg
33780 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c  regate function,
33790 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63   SQLite.** alloc
337a0 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79  ates N of memory
337b0 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61  , zeroes out tha
337c0 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
337d0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a  turns a pointer.
337e0 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65  ** to the new me
337f0 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64  mory. ^On second
33800 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
33810 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
33820 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
33830 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20  ntext() for the 
33840 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
33850 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
33860 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75  ,.** the same bu
33870 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  ffer is returned
33880 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65  .  Sqlite3_aggre
33890 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69  gate_context() i
338a0 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61  s normally.** ca
338b0 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61  lled once for ea
338c0 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ch invocation of
338d0 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62   the xStep callb
338e0 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65  ack and then one
338f0 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68  .** last time wh
33900 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  en the xFinal ca
33910 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
33920 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f  d.  ^(When no ro
33930 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61  ws match.** an a
33940 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20  ggregate query, 
33950 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c  the xStep() call
33960 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72  back of the aggr
33970 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  egate function.*
33980 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
33990 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64   is never called
339a0 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73   and xFinal() is
339b0 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20   called exactly 
339c0 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73  once..** In thos
339d0 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33  e cases, sqlite3
339e0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
339f0 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61  xt() might be ca
33a00 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20  lled for the.** 
33a10 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20  first time from 
33a20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e  within xFinal().
33a30 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
33a40 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
33a50 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
33a60 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e  tine returns a N
33a70 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20  ULL pointer .** 
33a80 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65  when first calle
33a90 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74  d if N is less t
33aa0 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
33ab0 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d  zero or if a mem
33ac0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20  ory.** allocate 
33ad0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
33ae0 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74  .** ^(The amount
33af0 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61   of space alloca
33b00 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61  ted by sqlite3_a
33b10 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
33b20 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65  (C,N) is.** dete
33b30 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20  rmined by the N 
33b40 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72  parameter on fir
33b50 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  st successful ca
33b60 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68  ll.  Changing th
33b70 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20  e.** value of N 
33b80 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
33b90 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ll to sqlite3_ag
33ba0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
33bb0 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  ) within.** the 
33bc0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
33bd0 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
33be0 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65   will not resize
33bf0 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
33c00 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69  llocation.)^  Wi
33c10 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  thin the xFinal 
33c20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20  callback, it is 
33c30 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74  customary to set
33c40 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73  .** N=0 in calls
33c50 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
33c60 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
33c70 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a  N) so that no .*
33c80 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f  * pointless memo
33c90 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f  ry allocations o
33ca0 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ccur..**.** ^SQL
33cb0 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
33cc0 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f  y frees the memo
33cd0 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ry allocated by 
33ce0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
33cf0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
33d00 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61  when the aggrega
33d10 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  te query conclud
33d20 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
33d30 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  rst parameter mu
33d40 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20  st be a copy of 
33d50 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
33d60 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75  context | SQL fu
33d70 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20  nction context] 
33d80 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73  that is the firs
33d90 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  t parameter.** t
33da0 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78  o the xStep or x
33db0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72  Final callback r
33dc0 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c  outine that impl
33dd0 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65  ements the aggre
33de0 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gate.** function
33df0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
33e00 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
33e10 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
33e20 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
33e30 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61  h.** the aggrega
33e40 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
33e50 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
33e60 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67  oid *sqlite3_agg
33e70 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
33e80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33e90 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
33ea0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
33eb0 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
33ec0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
33ed0 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
33ee0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
33ef0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
33f00 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
33f10 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
33f20 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
33f30 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
33f40 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
33f50 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
33f60 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
33f70 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
33f80 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
33f90 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
33fa0 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
33fb0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
33fc0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
33fd0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
33fe0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
33ff0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
34000 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
34010 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
34020 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
34030 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
34040 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
34050 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  d *sqlite3_user_
34060 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
34070 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
34080 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
34090 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72  e Connection For
340a0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
340b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
340c0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
340d0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
340e0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
340f0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
34100 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
34110 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31  nnection] (the 1
34120 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
34130 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
34140 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
34150 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
34160 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
34170 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
34180 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
34190 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
341a0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
341b0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
341c0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
341d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
341e0 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
341f0 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
34200 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
34210 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
34220 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ata.**.** These 
34230 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
34240 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67   used by (non-ag
34250 67 72 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e  gregate) SQL fun
34260 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73  ctions to.** ass
34270 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20  ociate metadata 
34280 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
34290 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
342a0 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
342b0 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
342c0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
342d0 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
342e0 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
342f0 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
34300 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
34310 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
34320 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74  sociated metadat
34330 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
34340 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a  ed.  An example.
34350 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69 73  ** of where this
34360 20 6d 69 67 68 74 20 62 65 20 75 73 65 66 75 6c   might be useful
34370 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72   is in a regular
34380 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
34390 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  hing.** function
343a0 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
343b0 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
343c0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
343d0 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61   can be stored a
343e0 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73  s.** metadata as
343f0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
34400 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  e pattern string
34410 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c  .  .** Then as l
34420 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74 74 65  ong as the patte
34430 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e  rn string remain
34440 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74  s the same,.** t
34450 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
34460 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
34470 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
34480 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
34490 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
344a0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ame function..**
344b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
344c0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
344d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
344e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
344f0 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  e metadata.** as
34500 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20  sociated by the 
34510 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
34520 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77  ata() function w
34530 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
34540 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f  ment.** value to
34550 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34560 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
34570 6e 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  n. ^If there is 
34580 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  no metadata.** a
34590 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
345a0 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  he function argu
345b0 6d 65 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74  ment, this sqlit
345c0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
345d0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65   interface.** re
345e0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
345f0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
34600 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
34610 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e  data(C,N,P,X) in
34620 74 65 72 66 61 63 65 20 73 61 76 65 73 20 50 20  terface saves P 
34630 61 73 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  as metadata for 
34640 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75  the N-th.** argu
34650 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c  ment of the appl
34660 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34670 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73  function.  ^Subs
34680 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
34690 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  to sqlite3_get_a
346a0 75 78 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75  uxdata(C,N) retu
346b0 72 6e 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f  rn P from the mo
346c0 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c  st recent.** sql
346d0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
346e0 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69  (C,N,P,X) call i
346f0 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  f the metadata i
34700 73 20 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72  s still valid or
34710 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20  .** NULL if the 
34720 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
34730 6e 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20  n discarded..** 
34740 5e 41 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c  ^After each call
34750 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
34760 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
34770 20 77 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20   where X is not 
34780 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  NULL,.** SQLite 
34790 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
347a0 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
347b0 69 6f 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d  ion X with param
347c0 65 74 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a  eter P exactly.*
347d0 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65  * once, when the
347e0 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 69 73   metadata is dis
347f0 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74  carded..** SQLit
34800 65 20 69 73 20 66 72 65 65 20 74 6f 20 64 69 73  e is free to dis
34810 63 61 72 64 20 74 68 65 20 6d 65 74 61 64 61 74  card the metadat
34820 61 20 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69  a at any time, i
34830 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a  ncluding: <ul>.*
34840 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20  * <li> when the 
34850 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75  corresponding fu
34860 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
34870 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20   changes, or.** 
34880 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74  <li> when [sqlit
34890 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
348a0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
348b0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f  ()] is called fo
348c0 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51  r the.**      SQ
348d0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a  L statement, or.
348e0 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c  ** <li> when sql
348f0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
34900 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67  () is invoked ag
34910 61 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ain on the same 
34920 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a  parameter, or.**
34930 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65   <li> during the
34940 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65   original sqlite
34950 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
34960 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f  call when a memo
34970 72 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f  ry .**      allo
34980 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
34990 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  urs. </ul>)^.**.
349a0 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74  ** Note the last
349b0 20 62 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69   bullet in parti
349c0 63 75 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74  cular.  The dest
349d0 72 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20  ructor X in .** 
349e0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
349f0 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67  ata(C,N,P,X) mig
34a00 68 74 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d  ht be called imm
34a10 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
34a20 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
34a30 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
34a40 74 65 72 66 61 63 65 20 65 76 65 6e 20 72 65 74  terface even ret
34a50 75 72 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c  urns.  Hence sql
34a60 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
34a70 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  ().** should be 
34a80 63 61 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20  called near the 
34a90 65 6e 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74  end of the funct
34aa0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
34ab0 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75  on and the.** fu
34ac0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
34ad0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
34ae0 20 6d 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66   make any use of
34af0 20 50 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69   P after.** sqli
34b00 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
34b10 29 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ) has been calle
34b20 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72  d..**.** ^(In pr
34b30 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61  actice, metadata
34b40 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65   is preserved be
34b50 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63  tween function c
34b60 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63  alls for.** func
34b70 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tion parameters 
34b80 74 68 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65  that are compile
34b90 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c  -time constants,
34ba0 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72   including liter
34bb0 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64  al.** values and
34bc0 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e   [parameters] an
34bd0 64 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f  d expressions co
34be0 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20  mposed from the 
34bf0 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  same.)^.**.** Th
34c00 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
34c10 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
34c20 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
34c30 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
34c40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
34c50 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
34c60 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
34c70 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
34c80 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
34c90 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65  .void sqlite3_se
34ca0 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
34cb0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
34cc0 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28  N, void*, void (
34cd0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a  *)(void*));.../*
34ce0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
34cf0 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67  nstants Defining
34d00 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63   Special Destruc
34d10 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a  tor Behavior.**.
34d20 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
34d30 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
34d40 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
34d50 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
34d60 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
34d70 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
34d80 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
34d90 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
34da0 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73  )].  ^If the des
34db0 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
34dc0 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
34dd0 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
34de0 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
34df0 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
34e00 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
34e10 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
34e20 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
34e30 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
34e40 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45    ^The.** SQLITE
34e50 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
34e60 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
34e70 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
34e80 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
34e90 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
34ea0 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
34eb0 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
34ec0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
34ed0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
34ee0 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
34ef0 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
34f00 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
34f10 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
34f20 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
34f30 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
34f40 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70  ompilers..*/.typ
34f50 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
34f60 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
34f70 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
34f80 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
34f90 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
34fa0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
34fb0 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
34fc0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
34fd0 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
34fe0 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
34ff0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
35000 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
35010 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
35020 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  tion.**.** These
35030 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
35040 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20  ed by the xFunc 
35050 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
35060 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c  cks that.** impl
35070 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69  ement SQL functi
35080 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
35090 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c  es.  See.** [sql
350a0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
350b0 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
350c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
350d0 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72  tion16()].** for
350e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
350f0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
35100 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77  hese functions w
35110 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69  ork very much li
35120 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65  ke the [paramete
35130 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c  r binding] famil
35140 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  y of.** function
35150 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76  s used to bind v
35160 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61  alues to host pa
35170 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70  rameters in prep
35180 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e  ared statements.
35190 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65  .** Refer to the
351a0 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
351b0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
351c0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
351d0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
351e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
351f0 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65  sult_blob() inte
35200 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
35210 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
35220 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
35230 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
35240 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f   be the BLOB who
35250 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f  se content is po
35260 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74  inted.** to by t
35270 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
35280 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73  ter and which is
35290 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68   N bytes long wh
352a0 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
352b0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
352c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
352d0 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
352e0 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73  lob() interfaces
352f0 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20   set the result 
35300 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
35310 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35320 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42  nction to be a B
35330 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  LOB containing a
35340 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73  ll zero.** bytes
35350 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20   and N bytes in 
35360 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73  size, where N is
35370 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
35380 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
35390 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
353a0 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
353b0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
353c0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
353d0 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
353e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
353f0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
35400 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
35410 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
35420 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
35430 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
35440 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35450 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
35460 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
35470 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  6() functions.**
35480 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65   cause the imple
35490 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74  mented SQL funct
354a0 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ion to throw an 
354b0 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53  exception..** ^S
354c0 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
354d0 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
354e0 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70   by the.** 2nd p
354f0 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
35500 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
35510 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
35520 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
35530 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66  * as the text of
35540 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
35550 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65  e.  ^SQLite inte
35560 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72  rprets the error
35570 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69  .** message stri
35580 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
35590 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
355a0 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65  s UTF-8. ^SQLite
355b0 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74  .** interprets t
355c0 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  he string from s
355d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
355e0 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31  ror16() as UTF-1
355f0 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62  6 in native.** b
35600 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20  yte order.  ^If 
35610 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
35620 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
35630 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
35640 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
35650 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
35660 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
35670 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68  Lite takes as th
35680 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
35690 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74  ge all text up t
356a0 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
356b0 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
356c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
356d0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
356e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
356f0 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ror() or.** sqli
35700 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
35710 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  16() is non-nega
35720 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
35730 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79   takes that many
35740 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63  .** bytes (not c
35750 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20  haracters) from 
35760 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
35770 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d  r as the error m
35780 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20  essage..** ^The 
35790 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
357a0 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
357b0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
357c0 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
357d0 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63  make a private c
357e0 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72  opy of the error
357f0 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65   message text be
35800 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74  fore.** they ret
35810 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  urn.  Hence, the
35820 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
35830 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65  n can deallocate
35840 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68   or.** modify th
35850 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65  e text after the
35860 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74  y return without
35870 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73   harm..** ^The s
35880 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35890 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
358a0 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
358b0 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
358c0 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
358d0 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
358e0 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
358f0 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66  nction.  ^By def
35900 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72  ault,.** the err
35910 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54  or code is SQLIT
35920 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62  E_ERROR.  ^A sub
35930 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
35940 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35950 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
35960 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35970 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65  r16() resets the
35980 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53   error code to S
35990 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a  QLITE_ERROR..**.
359a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
359b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
359c0 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  big() interface 
359d0 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
359e0 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72   throw an.** err
359f0 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  or indicating th
35a00 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  at a string or B
35a10 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20  LOB is too long 
35a20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a  to represent..**
35a30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35a40 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
35a50 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20  mem() interface 
35a60 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
35a70 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72   throw an.** err
35a80 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  or indicating th
35a90 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  at a memory allo
35aa0 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a  cation failed..*
35ab0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35ac0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69  3_result_int() i
35ad0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
35ae0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
35af0 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
35b00 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
35b10 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
35b20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
35b30 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
35b40 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
35b50 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
35b60 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
35b70 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61  _int64() interfa
35b80 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
35b90 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
35ba0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
35bb0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
35bc0 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74  to be the 64-bit
35bd0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
35be0 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
35bf0 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
35c00 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
35c10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
35c20 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
35c30 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
35c40 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
35c50 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35c60 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
35c70 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  e NULL..**.** ^T
35c80 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35c90 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65  t_text(), sqlite
35ca0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
35cb0 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  ),.** sqlite3_re
35cc0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c  sult_text16le(),
35cd0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
35ce0 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69  ult_text16be() i
35cf0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74  nterfaces.** set
35d00 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
35d10 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
35d20 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
35d30 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61  ction to be.** a
35d40 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69   text string whi
35d50 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  ch is represente
35d60 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d  d as UTF-8, UTF-
35d70 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
35d80 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  rder,.** UTF-16 
35d90 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f  little endian, o
35da0 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64  r UTF-16 big end
35db0 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
35dc0 79 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  y..** ^The sqlit
35dd0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 36 34  e3_result_text64
35de0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
35df0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
35e00 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 61 70 70 6c  ue of an.** appl
35e10 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
35e20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
35e30 20 74 65 78 74 20 73 74 72 69 6e 67 20 69 6e 20   text string in 
35e40 61 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 73  an encoding.** s
35e50 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
35e60 66 69 66 74 68 20 28 61 6e 64 20 6c 61 73 74 29  fifth (and last)
35e70 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63   parameter, whic
35e80 68 20 6d 75 73 74 20 62 65 20 6f 6e 65 0a 2a 2a  h must be one.**
35e90 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   of [SQLITE_UTF8
35ea0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
35eb0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
35ec0 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  BE], or [SQLITE_
35ed0 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20 5e 53 51  UTF16LE]..** ^SQ
35ee0 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
35ef0 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
35f00 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
35f10 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
35f20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
35f30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35f40 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
35f50 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
35f60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
35f70 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
35f80 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
35f90 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
35fa0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
35fb0 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
35fc0 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
35fd0 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67  ameter.** throug
35fe0 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
35ff0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
36000 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
36010 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
36020 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
36030 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
36040 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
36050 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
36060 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
36070 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
36080 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
36090 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
360a0 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
360b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
360c0 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
360d0 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20  ion result.  If 
360e0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
360f0 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  r is non-negativ
36100 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75  e, then it.** mu
36110 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
36120 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73  ffset into the s
36130 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20  tring where the 
36140 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
36150 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69  ould.** appear i
36160 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65  f the string whe
36170 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65  re NUL terminate
36180 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
36190 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a  haracters occur.
361a0 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  ** in the string
361b0 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65   at a byte offse
361c0 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74  t that is less t
361d0 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66  han the value of
361e0 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61   the 3rd.** para
361f0 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
36200 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
36210 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d   will contain em
36220 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20  bedded NULs and 
36230 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66  the.** result of
36240 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65   expressions ope
36250 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67  rating on string
36260 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  s with embedded 
36270 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
36280 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  d..** ^If the 4t
36290 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
362a0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
362b0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
362c0 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
362d0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
362e0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
362f0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
36300 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
36310 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
36320 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
36330 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
36340 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
36350 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
36360 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
36370 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
36380 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
36390 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
363a0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f  xt* interfaces o
363b0 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
363c0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
363d0 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
363e0 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ant SQLITE_STATI
363f0 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a  C, then SQLite.*
36400 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  * assumes that t
36410 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
36420 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e  result is in con
36430 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20  stant space and 
36440 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79  does not.** copy
36450 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
36460 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f  the parameter no
36470 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
36480 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65  tor on the conte
36490 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61  nt.** when it ha
364a0 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
364b0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
364c0 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
364d0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
364e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
364f0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
36500 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
36510 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
36520 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
36530 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
36540 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20  .** then SQLite 
36550 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
36560 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
36570 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66  space obtained f
36580 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  rom.** from [sql
36590 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62  ite3_malloc()] b
365a0 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
365b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
365c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
365d0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
365e0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  ts the result of
365f0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
36600 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
36610 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70  tion to be a cop
36620 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74  y the.** [unprot
36630 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
36640 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63  lue] object spec
36650 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64  ified by the 2nd
36660 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68   parameter.  ^Th
36670 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  e.** sqlite3_res
36680 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
36690 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
366a0 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
366b0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20  e3_value].** so 
366c0 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
366d0 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
366e0 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
366f0 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
36700 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
36710 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
36720 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
36730 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
36740 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72   harm..** ^A [pr
36750 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
36760 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61  value] object ma
36770 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64  y always be used
36780 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e   where an.** [un
36790 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
367a0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
367b0 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20  is required, so 
367c0 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f  either.** kind o
367d0 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
367e0 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20  ] object can be 
367f0 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69  used with this i
36800 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
36810 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  If these routine
36820 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  s are called fro
36830 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66  m within the dif
36840 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a  ferent thread.**
36850 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f   than the one co
36860 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70  ntaining the app
36870 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36880 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72   function that r
36890 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b  eceived.** the [
368a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
368b0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65   pointer, the re
368c0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
368d0 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ned..*/.void sql
368e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
368f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36900 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
36910 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
36920 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
36930 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 36 34  e3_result_blob64
36940 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36950 2a 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 0a 20  *,const void*,. 
36960 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36970 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
36980 33 5f 75 69 6e 74 36 34 2c 76 6f 69 64 28 2a 29  3_uint64,void(*)
36990 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
369a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
369b0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
369c0 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
369d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
369e0 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65  ult_error(sqlite
369f0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
36a00 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76  t char*, int);.v
36a10 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
36a20 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74  lt_error16(sqlit
36a30 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
36a40 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  st void*, int);.
36a50 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36a60 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
36a70 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36a80 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
36a90 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
36aa0 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  mem(sqlite3_cont
36ab0 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
36ac0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36ad0 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f  _code(sqlite3_co
36ae0 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
36af0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36b00 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  t_int(sqlite3_co
36b10 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
36b20 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36b30 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  t_int64(sqlite3_
36b40 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
36b50 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73  3_int64);.void s
36b60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
36b70 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ll(sqlite3_conte
36b80 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
36b90 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73  e3_result_text(s
36ba0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36bb0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
36bc0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
36bd0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
36be0 5f 72 65 73 75 6c 74 5f 74 65 78 74 36 34 28 73  _result_text64(s
36bf0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36c00 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c   const char*,sql
36c10 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20  ite3_uint64,.   
36c20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36c30 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28          void(*)(
36c40 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64  void*), unsigned
36c50 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b   char encoding);
36c60 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
36c70 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69  sult_text16(sqli
36c80 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
36c90 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
36ca0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
36cb0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
36cc0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71  sult_text16le(sq
36cd0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36ce0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
36cf0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
36d00 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36d10 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73  esult_text16be(s
36d20 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36d30 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
36d40 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
36d50 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
36d60 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c  result_value(sql
36d70 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
36d80 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
36d90 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36da0 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ult_zeroblob(sql
36db0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
36dc0 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
36dd0 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e  PI3REF: Define N
36de0 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71  ew Collating Seq
36df0 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  uences.**.** ^Th
36e00 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64  ese functions ad
36e10 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f  d, remove, or mo
36e20 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f  dify a [collatio
36e30 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  n] associated.**
36e40 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
36e50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36e60 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65  specified as the
36e70 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
36e80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
36e90 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
36ea0 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  n is a UTF-8 str
36eb0 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  ing.** for sqlit
36ec0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36ed0 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ion() and sqlite
36ee0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
36ef0 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61  on_v2().** and a
36f00 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
36f10 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
36f20 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
36f30 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36f40 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74  16()..** ^Collat
36f50 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63  ion names that c
36f60 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 63  ompare equal acc
36f70 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74  ording to [sqlit
36f80 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61  e3_strnicmp()] a
36f90 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
36fa0 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20   to be the same 
36fb0 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  name..**.** ^(Th
36fc0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
36fd0 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 74   (eTextRep) must
36fe0 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   be one of the c
36ff0 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c  onstants:.** <ul
37000 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
37010 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e  E_UTF8],.** <li>
37020 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
37030 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
37040 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
37050 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
37060 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  16], or.** <li> 
37070 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
37080 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  IGNED]..** </ul>
37090 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74  )^.** ^The eText
370a0 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74  Rep argument det
370b0 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f  ermines the enco
370c0 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20  ding of strings 
370d0 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65  passed.** to the
370e0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
370f0 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43  ion callback, xC
37100 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65  allback..** ^The
37110 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20   [SQLITE_UTF16] 
37120 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  and [SQLITE_UTF1
37130 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65  6_ALIGNED] value
37140 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a  s for eTextRep.*
37150 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20  * force strings 
37160 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 68  to be UTF16 with
37170 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
37180 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  er..** ^The [SQL
37190 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
371a0 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65  D] value for eTe
371b0 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 72  xtRep forces str
371c0 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a  ings to begin.**
371d0 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65   on an even byte
371e0 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20   address..**.** 
371f0 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75  ^The fourth argu
37200 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61  ment, pArg, is a
37210 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  n application da
37220 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  ta pointer that 
37230 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72  is passed.** thr
37240 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
37250 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
37260 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
37270 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  tion callback..*
37280 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
37290 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62  argument, xCallb
372a0 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65  ack, is a pointe
372b0 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  r to the collati
372c0 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ng function..** 
372d0 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74  ^Multiple collat
372e0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61  ing functions ca
372f0 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  n be registered 
37300 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e  using the same n
37310 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20  ame but.** with 
37320 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52  different eTextR
37330 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e  ep parameters an
37340 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  d SQLite will us
37350 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66  e whichever.** f
37360 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
37370 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
37380 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66  t of data transf
37390 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  ormation..** ^If
373a0 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61   the xCallback a
373b0 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20  rgument is NULL 
373c0 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  then the collati
373d0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a  ng function is.*
373e0 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65  * deleted.  ^Whe
373f0 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20  n all collating 
37400 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67  functions having
37410 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61   the same name a
37420 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74  re deleted,.** t
37430 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  hat collation is
37440 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c   no longer usabl
37450 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f  e..**.** ^The co
37460 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
37470 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
37480 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79  oked with a copy
37490 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a   of the pArg .**
374a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
374b0 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69  a pointer and wi
374c0 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69  th two strings i
374d0 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  n the encoding s
374e0 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
374f0 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75  he eTextRep argu
37500 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61  ment.  The colla
37510 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
37520 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20  st return an.** 
37530 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20  integer that is 
37540 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20  negative, zero, 
37550 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69  or positive.** i
37560 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69  f the first stri
37570 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c  ng is less than,
37580 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72   equal to, or gr
37590 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73  eater than the s
375a0 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63  econd,.** respec
375b0 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61  tively.  A colla
375c0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
375d0 73 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  st always return
375e0 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72   the same answer
375f0 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61  .** given the sa
37600 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74  me inputs.  If t
37610 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61  wo or more colla
37620 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
37630 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a  re registered.**
37640 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   to the same col
37650 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69  lation name (usi
37660 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65  ng different eTe
37670 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68  xtRep values) th
37680 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67  en all.** must g
37690 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e  ive an equivalen
376a0 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e  t answer when in
376b0 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76  voked with equiv
376c0 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a  alent strings..*
376d0 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  * The collating 
376e0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62  function must ob
376f0 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ey the following
37700 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20   properties for 
37710 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41  all.** strings A
37720 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a  , B, and C:.**.*
37730 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49  * <ol>.** <li> I
37740 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41  f A==B then B==A
37750 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d  ..** <li> If A==
37760 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20  B and B==C then 
37770 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  A==C..** <li> If
37780 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67   A&lt;B THEN B&g
37790 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  t;A..** <li> If 
377a0 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b  A&lt;B and B&lt;
377b0 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a  C then A&lt;C..*
377c0 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </ol>.**.** If
377d0 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   a collating fun
377e0 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20  ction fails any 
377f0 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e  of the above con
37800 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61  straints and tha
37810 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66  t.** collating f
37820 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69  unction is  regi
37830 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c  stered and used,
37840 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
37850 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  or of SQLite.** 
37860 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
37870 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37880 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37890 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b  n_v2() works lik
378a0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
378b0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20  _collation().** 
378c0 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f  with the additio
378d0 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74  n that the xDest
378e0 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  roy callback is 
378f0 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20  invoked on pArg 
37900 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c  when.** the coll
37910 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
37920 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43  s deleted..** ^C
37930 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
37940 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77  ns are deleted w
37950 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65  hen they are ove
37960 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
37970 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  .** calls to the
37980 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
37990 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ion functions or
379a0 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61   when the.** [da
379b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
379c0 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69  n] is closed usi
379d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
379e0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  e()]..**.** ^The
379f0 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61   xDestroy callba
37a00 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e  ck is <u>not</u>
37a10 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a   called if the .
37a20 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
37a30 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
37a40 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e   function fails.
37a50 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
37a60 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  hat invoke.** sq
37a70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
37a80 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68  lation_v2() with
37a90 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73   a non-NULL xDes
37aa0 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68  troy argument sh
37ab0 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74  ould .** check t
37ac0 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61  he return code a
37ad0 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  nd dispose of th
37ae0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
37af0 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68  ta pointer.** th
37b00 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 20  emselves rather 
37b10 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53  than expecting S
37b20 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69  QLite to deal wi
37b30 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a  th it for them..
37b40 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 65  ** This is diffe
37b50 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20  rent from every 
37b60 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
37b70 65 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63  erface.  The inc
37b80 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69  onsistency .** i
37b90 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75  s unfortunate bu
37ba0 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  t cannot be chan
37bb0 67 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  ged without brea
37bc0 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a  king backwards .
37bd0 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
37be0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
37bf0 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  :  [sqlite3_coll
37c00 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
37c10 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
37c20 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
37c30 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
37c40 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
37c50 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ion(.  sqlite3*,
37c60 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
37c70 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
37c80 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
37c90 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
37ca0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
37cb0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
37cc0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
37cd0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
37ce0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
37cf0 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  2(.  sqlite3*, .
37d00 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
37d10 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
37d20 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
37d30 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
37d40 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
37d50 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
37d60 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20  const void*),.  
37d70 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
37d80 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
37d90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
37da0 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  lation16(.  sqli
37db0 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76  te3*, .  const v
37dc0 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e  oid *zName,.  in
37dd0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
37de0 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
37df0 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
37e00 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
37e10 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
37e20 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
37e30 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
37e40 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
37e50 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69  s.**.** ^To avoi
37e60 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69  d having to regi
37e70 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  ster all collati
37e80 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66  on sequences bef
37e90 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a  ore a database.*
37ea0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61  * can be used, a
37eb0 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
37ec0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
37ed0 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
37ee0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
37ef0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
37f00 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
37f10 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65  ever an undefine
37f20 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  d collation.** s
37f30 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69  equence is requi
37f40 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  red..**.** ^If t
37f50 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
37f60 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
37f70 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  the sqlite3_coll
37f80 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41  ation_needed() A
37f90 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  PI,.** then it i
37fa0 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d  s passed the nam
37fb0 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20  es of undefined 
37fc0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
37fd0 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a  ces as strings.*
37fe0 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  * encoded in UTF
37ff0 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  -8. ^If sqlite3_
38000 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
38010 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a  16() is used,.**
38020 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70   the names are p
38030 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20  assed as UTF-16 
38040 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76  in machine nativ
38050 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
38060 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68   ^A call to eith
38070 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c  er function repl
38080 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e  aces the existin
38090 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64  g collation-need
380a0 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ed callback..**.
380b0 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61  ** ^(When the ca
380c0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
380d0 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67  d, the first arg
380e0 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20  ument passed is 
380f0 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65  a copy.** of the
38100 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
38110 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   to sqlite3_coll
38120 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f  ation_needed() o
38130 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
38140 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
38150 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ).  The second a
38160 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64  rgument is the d
38170 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
38180 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72  ction.  The thir
38190 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
381a0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
381b0 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
381c0 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  6BE],.** or [SQL
381d0 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
381e0 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
381f0 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d  t desirable form
38200 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
38210 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75  n.** sequence fu
38220 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
38230 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
38240 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
38250 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71  me of the.** req
38260 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  uired collation 
38270 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a  sequence.)^.**.*
38280 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
38290 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72  unction should r
382a0 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69  egister the desi
382b0 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73  red collation us
382c0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
382d0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
382e0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
382f0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
38300 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
38310 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
38320 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69  tion_v2()]..*/.i
38330 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
38340 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73  tion_needed(.  s
38350 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
38360 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  *, .  void(*)(vo
38370 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
38380 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
38390 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  char*).);.int sq
383a0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
383b0 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69  needed16(.  sqli
383c0 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  te3*, .  void*,.
383d0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
383e0 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
383f0 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64  xtRep,const void
38400 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51  *).);..#ifdef SQ
38410 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f  LITE_HAS_CODEC./
38420 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
38430 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
38440 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
38450 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
38460 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
38470 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
38480 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
38490 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
384a0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
384b0 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
384c0 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
384d0 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
384e0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
384f0 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71  qlite3_key(.  sq
38500 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
38510 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
38520 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
38530 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
38540 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
38550 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
38560 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20  e key */.);.int 
38570 73 71 6c 69 74 65 33 5f 6b 65 79 5f 76 32 28 0a  sqlite3_key_v2(.
38580 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
38590 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
385a0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
385b0 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
385c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e  const char *zDbN
385d0 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20 2f  ame,           /
385e0 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  * Name of the da
385f0 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
38600 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
38610 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
38620 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  e key */.);../*.
38630 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65  ** Change the ke
38640 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74  y on an open dat
38650 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63  abase.  If the c
38660 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
38670 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70  is not.** encryp
38680 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ted, this routin
38690 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69  e will encrypt i
386a0 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f  t.  If pNew==0 o
386b0 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a  r nNew==0, the.*
386c0 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  * database is de
386d0 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  crypted..**.** T
386e0 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
386f0 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
38700 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
38710 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
38720 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
38730 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
38740 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74  3_rekey(.  sqlit
38750 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
38760 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
38770 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
38780 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
38790 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
387a0 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e  Key     /* The n
387b0 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74  ew key */.);.int
387c0 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 5f 76   sqlite3_rekey_v
387d0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
387e0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
387f0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
38800 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
38810 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
38820 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20  DbName,         
38830 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
3