/ Hex Artifact Content
Login

Artifact f433227d7f619887a1064913fa66cefa3da4349a:


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 4d 55 54  QLITE_CONFIG_MUT
20c0: 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75  EX].  ^(The retu
20d0: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a  rn value of the.
20e0: 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  ** sqlite3_threa
20f0: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
2100: 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20   shows only the 
2110: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74  compile-time set
2120: 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61  ting of.** threa
2130: 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e  d safety, not an
2140: 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67  y run-time chang
2150: 65 73 20 74 6f 20 74 68 61 74 20 73 65 74 74 69  es to that setti
2160: 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71  ng made by.** sq
2170: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20  lite3_config(). 
2180: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2190: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
21a0: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68   from sqlite3_th
21b0: 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73  readsafe().** is
21c0: 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61   unchanged by ca
21d0: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
21e0: 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  onfig().)^.**.**
21f0: 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64   See the [thread
2200: 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65  ing mode] docume
2210: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
2220: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
2230: 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  on..*/.int sqlit
2240: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f  e3_threadsafe(vo
2250: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
2260: 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
2270: 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65  onnection Handle
2280: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64  .** KEYWORDS: {d
2290: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
22a0: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f  on} {database co
22b0: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  nnections}.**.**
22c0: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74   Each open SQLit
22d0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  e database is re
22e0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70  presented by a p
22f0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
2300: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  tance of.** the 
2310: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
2320: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
2330: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
2340: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
2350: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
2360: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
2370: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
2380: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
2390: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
23a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
23b0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
23c0: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75   are its constru
23d0: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69  ctors, and [sqli
23e0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20  te3_close()].** 
23f0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
2400: 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73  se_v2()] are its
2410: 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54   destructors.  T
2420: 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74  here are many ot
2430: 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  her.** interface
2440: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73  s (such as.** [s
2450: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2460: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  2()], [sqlite3_c
2470: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2480: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2490: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
24a0: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74  )] to name but t
24b0: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d  hree) that are m
24c0: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20  ethods on an.** 
24d0: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a  sqlite3 object..
24e0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
24f0: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65  t sqlite3 sqlite
2500: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  3;../*.** CAPI3R
2510: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
2520: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57  er Types.** KEYW
2530: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
2540: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2550: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
2560: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
2570: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
2580: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
2590: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
25a0: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
25b0: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
25c0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
25d0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
25e0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
25f0: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
2600: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
2610: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2620: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  type definitions
2630: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f  ..** The sqlite_
2640: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2650: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
2660: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  e supported for 
2670: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
2680: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
2690: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
26a0: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
26b0: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73  lite_int64 types
26c0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
26d0: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  er values.** bet
26e0: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36  ween -9223372036
26f0: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39  854775808 and +9
2700: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2710: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e  07 inclusive.  ^
2720: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  The.** sqlite3_u
2730: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2740: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  _uint64 types ca
2750: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2760: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65  values .** betwe
2770: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37  en 0 and +184467
2780: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69  44073709551615 i
2790: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66  nclusive..*/.#if
27a0: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
27b0: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
27c0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
27d0: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
27e0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
27f0: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
2800: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
2810: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
2820: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
2830: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
2840: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
2850: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
2860: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2870: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
2880: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2890: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
28a0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
28b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
28c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
28d0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
28e0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
28f0: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
2900: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
2910: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
2920: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
2930: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
2940: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
2950: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
2960: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
2970: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
2980: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
2990: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
29a0: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
29b0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
29c0: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
29d0: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
29e0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
29f0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
2a00: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
2a10: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
2a20: 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
2a30: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2a40: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f   and sqlite3_clo
2a50: 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73  se_v2() routines
2a60: 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72 73   are destructors
2a70: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  .** for the [sql
2a80: 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  ite3] object..**
2a90: 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
2aa0: 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73  e3_close() and s
2ab0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2ac0: 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  ) return [SQLITE
2ad0: 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b  _OK] if.** the [
2ae0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2af0: 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  is successfully 
2b00: 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c  destroyed and al
2b10: 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  l associated.** 
2b20: 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64 65  resources are de
2b30: 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  allocated..**.**
2b40: 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
2b50: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2b60: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2b70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2b80: 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
2b90: 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  ts or unfinished
2ba0: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20   sqlite3_backup 
2bb0: 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c  objects then sql
2bc0: 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20  ite3_close().** 
2bd0: 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64  will leave the d
2be0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2bf0: 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75  on open and retu
2c00: 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
2c10: 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
2c20: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63  _close_v2() is c
2c30: 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e  alled with unfin
2c40: 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 20  alized prepared 
2c50: 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e  statements.** an
2c60: 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20  d/or unfinished 
2c70: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c  sqlite3_backups,
2c80: 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
2c90: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  se connection be
2ca0: 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73  comes.** an unus
2cb0: 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68  able "zombie" wh
2cc0: 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ich will automat
2cd0: 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f  ically be deallo
2ce0: 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a  cated when the.*
2cf0: 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64 20  * last prepared 
2d00: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e  statement is fin
2d10: 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61  alized or the la
2d20: 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  st sqlite3_backu
2d30: 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64  p is.** finished
2d40: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  .  The sqlite3_c
2d50: 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66  lose_v2() interf
2d60: 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20  ace is intended 
2d70: 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20  for use with.** 
2d80: 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74  host languages t
2d90: 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65 20  hat are garbage 
2da0: 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77  collected, and w
2db0: 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20 69  here the order i
2dc0: 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72  n which.** destr
2dd0: 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65  uctors are calle
2de0: 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a  d is arbitrary..
2df0: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
2e00: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74  ns should [sqlit
2e10: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
2e20: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65  nalize] all [pre
2e30: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2e40: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2e50: 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73  lob_close | clos
2e60: 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e  e] all [BLOB han
2e70: 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b  dles], and .** [
2e80: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66  sqlite3_backup_f
2e90: 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20  inish | finish] 
2ea0: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  all [sqlite3_bac
2eb0: 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73  kup] objects ass
2ec0: 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20  ociated.** with 
2ed0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2ee0: 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74  ject prior to at
2ef0: 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73  tempting to clos
2f00: 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e  e the object.  ^
2f10: 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c  If.** sqlite3_cl
2f20: 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  ose_v2() is call
2f30: 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73  ed on a [databas
2f40: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
2f50: 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20  at still has.** 
2f60: 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65  outstanding [pre
2f70: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2f80: 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ], [BLOB handles
2f90: 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71  ], and/or.** [sq
2fa0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2fb0: 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72 65  jects then it re
2fc0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
2fd0: 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f  ] and the deallo
2fe0: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73  cation.** of res
2ff0: 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72 72  ources is deferr
3000: 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72  ed until all [pr
3010: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3020: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
3030: 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  s],.** and [sqli
3040: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
3050: 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73  cts are also des
3060: 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  troyed..**.** ^I
3070: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  f an [sqlite3] o
3080: 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f 79  bject is destroy
3090: 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73  ed while a trans
30a0: 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a  action is open,.
30b0: 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ** the transacti
30c0: 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  on is automatica
30d0: 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  lly rolled back.
30e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72  .**.** The C par
30f0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
3100: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64  e3_close(C)] and
3110: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f   [sqlite3_close_
3120: 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  v2(C)].** must b
3130: 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a  e either a NULL.
3140: 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e  ** pointer or an
3150: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
3160: 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e  t pointer obtain
3170: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
3180: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
3190: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
31a0: 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
31b0: 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
31c0: 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63  not previously c
31d0: 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69  losed..** ^Calli
31e0: 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  ng sqlite3_close
31f0: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c  () or sqlite3_cl
3200: 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61 20  ose_v2() with a 
3210: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
3220: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61  argument is a ha
3230: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f  rmless no-op..*/
3240: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f  .int sqlite3_clo
3250: 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69 6e  se(sqlite3*);.in
3260: 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  t sqlite3_close_
3270: 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  v2(sqlite3*);../
3280: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
3290: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
32a0: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
32b0: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
32c0: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
32d0: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
32e0: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
32f0: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
3300: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
3310: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
3320: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
3330: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
3340: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
3350: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
3360: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
3370: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
3380: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
3390: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
33a0: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
33b0: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
33c0: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
33d0: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
33e0: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
33f0: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
3400: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
3410: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
3420: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
3430: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
3440: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
3450: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3460: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3470: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3480: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3490: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
34a0: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
34b0: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
34c0: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
34d0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
34e0: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
34f0: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
3500: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
3510: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
3520: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
3530: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
3540: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
3550: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3560: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3570: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3580: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3590: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
35a0: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
35b0: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
35c0: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
35d0: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
35e0: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
35f0: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
3600: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
3610: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3620: 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67  s relayed throug
3630: 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67  h to the 1st arg
3640: 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a  ument of each.**
3650: 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61   callback invoca
3660: 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63  tion.  ^If the c
3670: 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20  allback pointer 
3680: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3690: 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ).** is NULL, th
36a0: 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69  en no callback i
36b0: 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61  s ever invoked a
36c0: 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61  nd result rows a
36d0: 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a  re.** ignored..*
36e0: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f  *.** ^If an erro
36f0: 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65  r occurs while e
3700: 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51  valuating the SQ
3710: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73  L statements pas
3720: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  sed into.** sqli
3730: 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e  te3_exec(), then
3740: 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
3750: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d  e current statem
3760: 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a  ent stops and.**
3770: 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74   subsequent stat
3780: 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70  ements are skipp
3790: 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68  ed.  ^If the 5th
37a0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
37b0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
37c0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
37d0: 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61   any error messa
37e0: 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  ge is written in
37f0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
3800: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
3810: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
3820: 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68  d passed back th
3830: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
3840: 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61  rameter..** To a
3850: 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  void memory leak
3860: 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  s, the applicati
3870: 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65  on should invoke
3880: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
3890: 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65  ].** on error me
38a0: 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65  ssage strings re
38b0: 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74  turned through t
38c0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
38d0: 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65   of.** of sqlite
38e0: 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 74  3_exec() after t
38f0: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
3900: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f   string is no lo
3910: 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20  nger needed..** 
3920: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
3930: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
3940: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3950: 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72  ULL and no error
3960: 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e  s.** occur, then
3970: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3980: 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72  sets the pointer
3990: 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 61   in its 5th para
39a0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c  meter to.** NULL
39b0: 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
39c0: 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  g..**.** ^If an 
39d0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
39e0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
39f0: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71  non-zero, the sq
3a00: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3a10: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
3a20: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74  SQLITE_ABORT wit
3a30: 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  hout invoking th
3a40: 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e  e callback again
3a50: 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20   and.** without 
3a60: 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73  running any subs
3a70: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65  equent SQL state
3a80: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
3a90: 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  e 2nd argument t
3aa0: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  o the sqlite3_ex
3ab0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75  ec() callback fu
3ac0: 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a  nction is the.**
3ad0: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
3ae0: 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
3af0: 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 75  .  ^The 3rd argu
3b00: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
3b10: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61  te3_exec().** ca
3b20: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
3b30: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
3b40: 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e  o strings obtain
3b50: 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a  ed as if from.**
3b60: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
3b70: 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f  _text()], one fo
3b80: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20  r each column.  
3b90: 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f  ^If an element o
3ba0: 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  f a.** result ro
3bb0: 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  w is NULL then t
3bc0: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
3bd0: 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
3be0: 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74  for the.** sqlit
3bf0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3c00: 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ck is a NULL poi
3c10: 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20  nter.  ^The 4th 
3c20: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
3c30: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3c40: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  ) callback is an
3c50: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3c60: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68  rs to strings wh
3c70: 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72  ere each.** entr
3c80: 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 65  y represents the
3c90: 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70   name of corresp
3ca0: 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f  onding result co
3cb0: 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64  lumn as obtained
3cc0: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3cd0: 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d  3_column_name()]
3ce0: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
3cf0: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
3d00: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3d10: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
3d20: 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  r, a pointer.** 
3d30: 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
3d40: 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  ng, or a pointer
3d50: 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f   that contains o
3d60: 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61  nly whitespace a
3d70: 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f  nd/or .** SQL co
3d80: 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20  mments, then no 
3d90: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
3da0: 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64  re evaluated and
3db0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
3dc0: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e   is not changed.
3dd0: 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69  .**.** Restricti
3de0: 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ons:.**.** <ul>.
3df0: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3e00: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73  ication must ins
3e10: 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73 74  ure that the 1st
3e20: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3e30: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3e40: 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 20       is a valid 
3e50: 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  and open [databa
3e60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
3e70: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3e80: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3e90: 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61   close the [data
3ea0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
3eb0: 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a   specified by.**
3ec0: 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61        the 1st pa
3ed0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
3ee0: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20  e3_exec() while 
3ef0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3f00: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c  s running..** <l
3f10: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
3f20: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69  on must not modi
3f30: 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  fy the SQL state
3f40: 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64  ment text passed
3f50: 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68   into.**      th
3f60: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
3f70: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
3f80: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  ) while sqlite3_
3f90: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e  exec() is runnin
3fa0: 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69  g..** </ul>.*/.i
3fb0: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
3fc0: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
3fd0: 20 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 2f 2a                /*
3ff0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
4000: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
4010: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
4020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4030: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
4040: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
4050: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
4060: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
4070: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
4080: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
4090: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  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 2f 2a                /*
40c0: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
40d0: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
40e0: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4100: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
4110: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
4120: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
4130: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
4140: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4150: 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64  RDS: {result cod
4160: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a  e definitions}.*
4170: 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65  *.** Many SQLite
4180: 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
4190: 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73  n an integer res
41a0: 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68  ult code from th
41b0: 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68  e set shown.** h
41c0: 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ere in order to 
41d0: 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73 73  indicate success
41e0: 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a   or failure..**.
41f0: 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64  ** New error cod
4200: 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
4210: 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
4220: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
4230: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65  .** See also: [e
4240: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4250: 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d  ode definitions]
4260: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
4270: 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20  TE_OK           
4280: 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75  0   /* Successfu
4290: 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62  l result */./* b
42a0: 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f  eginning-of-erro
42b0: 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69  r-codes */.#defi
42c0: 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  ne SQLITE_ERROR 
42d0: 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51         1   /* SQ
42e0: 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69  L error or missi
42f0: 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ng database */.#
4300: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4310: 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f  TERNAL     2   /
4320: 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63  * Internal logic
4330: 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65   error in SQLite
4340: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4350: 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20  TE_PERM         
4360: 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65  3   /* Access pe
4370: 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20  rmission denied 
4380: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4390: 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 34  E_ABORT        4
43a0: 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72     /* Callback r
43b0: 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 64  outine requested
43c0: 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65   an abort */.#de
43d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
43e0: 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20           5   /* 
43f0: 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  The database fil
4400: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
4410: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
4420: 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 2f  CKED       6   /
4430: 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65  * A table in the
4440: 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63   database is loc
4450: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
4460: 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20  QLITE_NOMEM     
4470: 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c     7   /* A mall
4480: 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23  oc() failed */.#
4490: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
44a0: 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f  ADONLY     8   /
44b0: 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69  * Attempt to wri
44c0: 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61  te a readonly da
44d0: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
44e0: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55  e SQLITE_INTERRU
44f0: 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65  PT    9   /* Ope
4500: 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65  ration terminate
4510: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74  d by sqlite3_int
4520: 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69  errupt()*/.#defi
4530: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  ne SQLITE_IOERR 
4540: 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f        10   /* So
4550: 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20  me kind of disk 
4560: 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72  I/O error occurr
4570: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4580: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20  LITE_CORRUPT    
4590: 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74   11   /* The dat
45a0: 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65  abase disk image
45b0: 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f   is malformed */
45c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
45d0: 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20  NOTFOUND    12  
45e0: 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f   /* Unknown opco
45f0: 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69  de in sqlite3_fi
4600: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a  le_control() */.
4610: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4620: 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20  ULL        13   
4630: 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69  /* Insertion fai
4640: 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61  led because data
4650: 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a  base is full */.
4660: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4670: 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20  ANTOPEN    14   
4680: 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65  /* Unable to ope
4690: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
46a0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
46b0: 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20  QLITE_PROTOCOL  
46c0: 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61    15   /* Databa
46d0: 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c  se lock protocol
46e0: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
46f0: 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20  e SQLITE_EMPTY  
4700: 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74       16   /* Dat
4710: 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a  abase is empty *
4720: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4730: 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20  _SCHEMA      17 
4740: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4750: 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64  e schema changed
4760: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4770: 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31  TE_TOOBIG      1
4780: 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72  8   /* String or
4790: 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69   BLOB exceeds si
47a0: 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66  ze limit */.#def
47b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
47c0: 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41  RAINT  19   /* A
47d0: 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73  bort due to cons
47e0: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
47f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4800: 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32  TE_MISMATCH    2
4810: 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65  0   /* Data type
4820: 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65   mismatch */.#de
4830: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55  fine SQLITE_MISU
4840: 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20  SE      21   /* 
4850: 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63  Library used inc
4860: 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66  orrectly */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53  ine SQLITE_NOLFS
4880: 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55         22   /* U
4890: 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20  ses OS features 
48a0: 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e  not supported on
48b0: 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65   host */.#define
48c0: 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20   SQLITE_AUTH    
48d0: 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68      23   /* Auth
48e0: 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64  orization denied
48f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4900: 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32  TE_FORMAT      2
4910: 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79  4   /* Auxiliary
4920: 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74   database format
4930: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
4940: 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20  e SQLITE_RANGE  
4950: 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64       25   /* 2nd
4960: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
4970: 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f  lite3_bind out o
4980: 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69  f range */.#defi
4990: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42  ne SQLITE_NOTADB
49a0: 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69        26   /* Fi
49b0: 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69  le opened that i
49c0: 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
49d0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
49e0: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20   SQLITE_NOTICE  
49f0: 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69      27   /* Noti
4a00: 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73  fications from s
4a10: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4a20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57  #define SQLITE_W
4a30: 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20  ARNING     28   
4a40: 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d  /* Warnings from
4a50: 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a   sqlite3_log() *
4a60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4a70: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
4a80: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4a90: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
4aa0: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
4ab0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
4ac0: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
4ad0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4ae0: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
4af0: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
4b00: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4b10: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
4b20: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
4b30: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4b40: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
4b50: 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69  result code defi
4b60: 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49  nitions}.**.** I
4b70: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f  n its default co
4b80: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c  nfiguration, SQL
4b90: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73  ite API routines
4ba0: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33   return one of 3
4bb0: 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65  0 integer.** [re
4bc0: 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f  sult codes].  Ho
4bd0: 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63  wever, experienc
4be0: 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74  e has shown that
4bf0: 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73   many of.** thes
4c00: 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  e result codes a
4c10: 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72  re too coarse-gr
4c20: 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20  ained.  They do 
4c30: 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a  not provide as.*
4c40: 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69  * much informati
4c50: 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d  on about problem
4c60: 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73  s as programmers
4c70: 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e   might like.  In
4c80: 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a   an effort to.**
4c90: 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e   address this, n
4ca0: 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ewer versions of
4cb0: 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e   SQLite (version
4cc0: 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72   3.3.8 and later
4cd0: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
4ce0: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
4cf0: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
4d00: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
4d10: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
4d20: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
4d30: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b   errors. These [
4d40: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4d50: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c  codes] are enabl
4d60: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
4d70: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
4d80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
4d90: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
4da0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
4db0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
4dc0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68  ()] API.  Or, th
4dd0: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20  e extended code 
4de0: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20  for.** the most 
4df0: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e  recent error can
4e00: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69   be obtained usi
4e10: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
4e20: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
4e30: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
4e40: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
4e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
4e60: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
4e70: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4e80: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
4e90: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
4ea0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
4eb0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4ec0: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
4ed0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4ee0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
4ef0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f00: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
4f10: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f20: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
4f30: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4f40: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
4f50: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
4f60: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
4f70: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4f80: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
4f90: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4fa0: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
4fb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4fc0: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
4fd0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4fe0: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
4ff0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5000: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
5010: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5020: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
5030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5040: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
5050: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5060: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
5070: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5080: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
5090: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50a0: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
50b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
50c0: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
50d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50e0: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
50f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5100: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
5110: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5120: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
5130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5140: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
5150: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5160: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
5170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5180: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
5190: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
51a0: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
51b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
51c0: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
51d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
51e0: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
51f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5200: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
5210: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5220: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
5230: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5240: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
5250: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5260: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
5270: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5280: 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20  RR_SHMOPEN      
5290: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
52a0: 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64  RR | (18<<8)).#d
52b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
52c0: 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20  RR_SHMSIZE      
52d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
52e0: 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64  RR | (19<<8)).#d
52f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5300: 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20  RR_SHMLOCK      
5310: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5320: 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64  RR | (20<<8)).#d
5330: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5340: 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20  RR_SHMMAP       
5350: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5360: 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64  RR | (21<<8)).#d
5370: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5380: 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20  RR_SEEK         
5390: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53a0: 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64  RR | (22<<8)).#d
53b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53c0: 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20  RR_DELETE_NOENT 
53d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53e0: 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64  RR | (23<<8)).#d
53f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5400: 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20  RR_MMAP         
5410: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5420: 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64  RR | (24<<8)).#d
5430: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5440: 52 52 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20  RR_GETTEMPPATH  
5450: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5460: 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64  RR | (25<<8)).#d
5470: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5480: 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  RR_CONVPATH     
5490: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
54a0: 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64  RR | (26<<8)).#d
54b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
54c0: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
54d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
54e0: 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  KED |  (1<<8)).#
54f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5500: 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  SY_RECOVERY     
5510: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5520: 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a  SY   |  (1<<8)).
5530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
5540: 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20  USY_SNAPSHOT    
5550: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
5560: 55 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29  USY   |  (2<<8))
5570: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5580: 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44  CANTOPEN_NOTEMPD
5590: 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  IR      (SQLITE_
55a0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38  CANTOPEN | (1<<8
55b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
55c0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52  E_CANTOPEN_ISDIR
55d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
55e0: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c  E_CANTOPEN | (2<
55f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5600: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c  ITE_CANTOPEN_FUL
5610: 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  LPATH       (SQL
5620: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5630: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5640: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43  QLITE_CANTOPEN_C
5650: 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53  ONVPATH       (S
5660: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5670: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5680: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5690: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
56a0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
56b0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
56c0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
56d0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
56e0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
56f0: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<8)).#def
5700: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5710: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
5720: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5730: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  NLY | (2<<8)).#d
5740: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5750: 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20  DONLY_ROLLBACK  
5760: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5770: 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a  DONLY | (3<<8)).
5780: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5790: 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20  EADONLY_DBMOVED 
57a0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
57b0: 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29  EADONLY | (4<<8)
57c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
57d0: 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20  _ABORT_ROLLBACK 
57e0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
57f0: 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29  _ABORT | (2<<8))
5800: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5810: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b  CONSTRAINT_CHECK
5820: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5830: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c  CONSTRAINT | (1<
5840: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5850: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5860: 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c  OMMITHOOK   (SQL
5870: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5880: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5890: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
58a0: 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20  NT_FOREIGNKEY   
58b0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
58c0: 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  NT | (3<<8)).#de
58d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
58e0: 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20  TRAINT_FUNCTION 
58f0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5900: 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29  TRAINT | (4<<8))
5910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5920: 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55  CONSTRAINT_NOTNU
5930: 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  LL      (SQLITE_
5940: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c  CONSTRAINT | (5<
5950: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5960: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50  ITE_CONSTRAINT_P
5970: 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c  RIMARYKEY   (SQL
5980: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5990: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
59a0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
59b0: 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  NT_TRIGGER      
59c0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
59d0: 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  NT | (7<<8)).#de
59e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
59f0: 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20  TRAINT_UNIQUE   
5a00: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5a10: 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29  TRAINT | (8<<8))
5a20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a30: 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20  CONSTRAINT_VTAB 
5a40: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5a50: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c  CONSTRAINT | (9<
5a60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a70: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52  ITE_CONSTRAINT_R
5a80: 4f 57 49 44 20 20 20 20 20 20 20 20 28 53 51 4c  OWID        (SQL
5a90: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5aa0: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
5ab0: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52   SQLITE_NOTICE_R
5ac0: 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20  ECOVER_WAL      
5ad0: 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c  (SQLITE_NOTICE |
5ae0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5af0: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52   SQLITE_NOTICE_R
5b00: 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20  ECOVER_ROLLBACK 
5b10: 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c  (SQLITE_NOTICE |
5b20: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5b30: 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f   SQLITE_WARNING_
5b40: 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20  AUTOINDEX       
5b50: 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20  (SQLITE_WARNING 
5b60: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5b70: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53  e SQLITE_AUTH_US
5b80: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ER              
5b90: 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20   (SQLITE_AUTH | 
5ba0: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
5bb0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
5bc0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
5bd0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
5be0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
5bf0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
5c00: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
5c10: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
5c20: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
5c30: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5c40: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5c50: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5c60: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
5c70: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
5c80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5c90: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
5ca0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5cb0: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
5cc0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5cd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ce0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
5cf0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5d00: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
5d10: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d20: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d30: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
5d40: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5d50: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
5d60: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d80: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
5d90: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
5da0: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
5db0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5dc0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
5dd0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5de0: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
5df0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5e00: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
5e10: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5e20: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
5e30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5e40: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
5e50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5e60: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
5e70: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5e80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5e90: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
5ea0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5eb0: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
5ec0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5ed0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ee0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
5ef0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
5f00: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5f10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5f20: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
5f30: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
5f40: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5f50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5f60: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
5f70: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
5f80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5f90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5fa0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
5fb0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
5fc0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5fd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5fe0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
5ff0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
6000: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6010: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6020: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
6030: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
6040: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6050: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6060: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
6070: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
6080: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6090: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
60a0: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
60b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
60c0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
60d0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
60e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
60f0: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
6100: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
6110: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6120: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6130: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6140: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
6150: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
6160: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6170: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6180: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6190: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
61a0: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
61b0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
61c0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
61d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
61e0: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
61f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
6200: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6210: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
6220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6230: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
6240: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
6250: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
6260: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
6270: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
6280: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
6290: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
62a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
62b0: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
62c0: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
62d0: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
62e0: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
62f0: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
6300: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
6310: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
6320: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
6330: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
6340: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
6350: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
6360: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
6370: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
6380: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6390: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
63a0: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
63b0: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
63c0: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
63d0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
63e0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
63f0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
6400: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
6410: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
6420: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
6430: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
6440: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
6450: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
6460: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
6470: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
6480: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6490: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
64a0: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
64b0: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
64c0: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
64d0: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
64e0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
64f0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
6500: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
6510: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
6520: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
6530: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
6540: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6550: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
6560: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
6570: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
6580: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
6590: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
65a0: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
65b0: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
65c0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
65d0: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
65e0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
65f0: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
6600: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
6610: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
6620: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
6630: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
6640: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
6650: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
6660: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
6670: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
6680: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
6690: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
66a0: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
66b0: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
66c0: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
66d0: 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51  changed.  The SQ
66e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
66f0: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
6700: 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74  .** flag indicat
6710: 65 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61  e that a file ca
6720: 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20  nnot be deleted 
6730: 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a  when open.  The.
6740: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ** SQLITE_IOCAP_
6750: 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69  IMMUTABLE flag i
6760: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
6770: 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20  e file is on.** 
6780: 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20  read-only media 
6790: 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  and cannot be ch
67a0: 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72  anged even by pr
67b0: 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20  ocesses with.** 
67c0: 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65  elevated privile
67d0: 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ges..*/.#define 
67e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
67f0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20  MIC             
6800: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
6810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6820: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
6830: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6840: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
6850: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6860: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C1K             
6870: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
6880: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6890: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
68a0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
68b0: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
68c0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
68d0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
68e0: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
68f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6900: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
6910: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
6920: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6930: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
6940: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6950: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
6960: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6970: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20  OMIC32K         
6980: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
6990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
69a0: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
69b0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
69c0: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
69d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
69e0: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20  _APPEND         
69f0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
6a00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6a10: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
6a20: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6a30: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
6a40: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
6a50: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20  TABLE_WHEN_OPEN 
6a60: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66   0x00000800.#def
6a70: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a80: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
6a90: 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30  RITE    0x000010
6aa0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6ab0: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
6ac0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  E              0
6ad0: 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a  x00002000../*.**
6ae0: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
6af0: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a  Locking Levels.*
6b00: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
6b10: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
6b20: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
6b30: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
6b40: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
6b50: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
6b60: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
6b70: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
6b80: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
6b90: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6ba0: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
6bb0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
6bc0: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
6bd0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
6be0: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
6bf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6c00: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
6c10: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
6c20: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
6c30: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
6c40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
6c50: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
6c60: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
6c70: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
6c80: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65   Flags.**.** Whe
6c90: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
6ca0: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
6cb0: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
6cc0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6cd0: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
6ce0: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
6cf0: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
6d00: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6d10: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
6d20: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
6d30: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
6d40: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
6d50: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
6d60: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
6d70: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
6d80: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
6d90: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
6da0: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
6db0: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
6dc0: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20   be flushed. If 
6dd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
6de0: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a  its of the flag.
6df0: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ** equal SQLITE_
6e00: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61  SYNC_NORMAL, tha
6e10: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e  t means to use n
6e20: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
6e30: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74  mantics..** If t
6e40: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
6e50: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ts equal SQLITE_
6e60: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20  SYNC_FULL, that 
6e70: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
6e80: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
6e90: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
6ea0: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a  of fsync()..**.*
6eb0: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65  * Do not confuse
6ec0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6ed0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
6ee0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
6ef0: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  gs.** with the [
6f00: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
6f10: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b  us]=NORMAL and [
6f20: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
6f30: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74  us]=FULL.** sett
6f40: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63  ings.  The [sync
6f50: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20  hronous pragma] 
6f60: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20  determines when 
6f70: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20  calls to the.** 
6f80: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64  xSync VFS method
6f90: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69   occur and appli
6fa0: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72  es uniformly acr
6fb0: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d  oss all platform
6fc0: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  s..** The SQLITE
6fd0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6fe0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6ff0: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e  L flags determin
7000: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74  e how.** energet
7010: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f  ic or rigorous o
7020: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73  r forceful the s
7030: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ync operations a
7040: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d  re and.** only m
7050: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65  ake a difference
7060: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20   on Mac OSX for 
7070: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69  the default SQLi
7080: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69  te code..** (Thi
7090: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70  rd-party VFS imp
70a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67  lementations mig
70b0: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65  ht also make the
70c0: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
70d0: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53  between SQLITE_S
70e0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
70f0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
7100: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a   but among the.*
7110: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  * operating syst
7120: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70  ems natively sup
7130: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
7140: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a  , only Mac OSX.*
7150: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68  * cares about th
7160: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a  e difference.).*
7170: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7180: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20  _SYNC_NORMAL    
7190: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66      0x00002.#def
71a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
71b0: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78  FULL          0x
71c0: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51  00003.#define SQ
71d0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
71e0: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a  LY      0x00010.
71f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7200: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
7210: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a  en File Handle.*
7220: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
7230: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
7240: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
7250: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
7260: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
7270: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
7280: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
7290: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
72a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
72b0: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
72c0: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
72d0: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
72e0: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
72f0: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
7300: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
7310: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
7320: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
7330: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
7340: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
7350: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
7360: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
7370: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
7380: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
7390: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
73a0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
73b0: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
73c0: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
73d0: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
73e0: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
73f0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
7400: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
7410: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
7420: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
7430: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
7440: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
7450: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
7460: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72  bject.**.** Ever
7470: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79  y file opened by
7480: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7490: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
74a0: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20  populates an.** 
74b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
74c0: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20  bject (or, more 
74d0: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63  commonly, a subc
74e0: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  lass of the.** [
74f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7500: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69  ject) with a poi
7510: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
7520: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
7530: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  ct..** This obje
7540: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d  ct defines the m
7550: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
7560: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
7570: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61  perations.** aga
7580: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69  inst the open fi
7590: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  le represented b
75a0: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  y the [sqlite3_f
75b0: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  ile] object..**.
75c0: 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74  ** If the [sqlit
75d0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
75e0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
75f0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
7600: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
7610: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
7620: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
7630: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7640: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
7650: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
7660: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b  ed even if the [
7670: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7680: 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74  n] reported that
7690: 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65   it failed.  The
76a0: 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20  .** only way to 
76b0: 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74  prevent a call t
76c0: 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69  o xClose followi
76d0: 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c  ng a failed [sql
76e0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a  ite3_vfs.xOpen].
76f0: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73  ** is for the [s
7700: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7710: 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c  ] to set the sql
7720: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7730: 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f  ds element.** to
7740: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
7750: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
7760: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
7770: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
7780: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
7790: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
77a0: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
77b0: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
77c0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
77d0: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
77e0: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20  ice is a Mac OS 
77f0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
7800: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
7810: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
7820: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
7830: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
7840: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
7850: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
7860: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
7870: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
7880: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
7890: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
78a0: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
78b0: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
78c0: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
78d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
78e0: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
78f0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
7900: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
7910: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
7920: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
7930: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
7940: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
7950: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
7960: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
7970: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
7980: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
7990: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
79a0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
79b0: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
79c0: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
79d0: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
79e0: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
79f0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
7a00: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
7a10: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
7a20: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
7a30: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
7a40: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
7a50: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
7a60: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
7a70: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
7a80: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
7a90: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
7aa0: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
7ab0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
7ac0: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
7ad0: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
7ae0: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
7af0: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
7b00: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7b10: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
7b20: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
7b30: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
7b40: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
7b50: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
7b60: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
7b70: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
7b80: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
7b90: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
7ba0: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
7bb0: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
7bc0: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
7bd0: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
7be0: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
7bf0: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
7c00: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
7c10: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
7c20: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
7c30: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
7c40: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
7c50: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
7c60: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
7c70: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
7c80: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
7c90: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
7ca0: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
7cb0: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
7cc0: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
7cd0: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
7ce0: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
7cf0: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
7d00: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
7d10: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
7d20: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
7d30: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
7d40: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
7d50: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
7d60: 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f  * A [file contro
7d70: 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74  l opcodes | list
7d80: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
7d90: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
7da0: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
7db0: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
7dc0: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
7dd0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
7de0: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
7df0: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
7e00: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
7e10: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
7e20: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7e30: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
7e40: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
7e50: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
7e60: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
7e70: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
7e80: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
7e90: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
7ea0: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
7eb0: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
7ec0: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
7ed0: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
7ee0: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
7ef0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
7f00: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
7f10: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
7f20: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
7f30: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
7f40: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
7f50: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
7f60: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
7f70: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
7f80: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
7f90: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
7fa0: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
7fb0: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
7fc0: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
7fd0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7fe0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7ff0: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
8000: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8010: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
8020: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8030: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
8040: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8050: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
8060: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8070: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
8080: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8090: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
80a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
80b0: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
80c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
80d0: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
80e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
80f0: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
8100: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
8110: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
8120: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8130: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
8140: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
8150: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8160: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
8170: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
8180: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
8190: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
81a0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
81b0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
81c0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
81d0: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
81e0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
81f0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
8200: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
8210: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
8220: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
8230: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
8240: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
8250: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8260: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
8270: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
8280: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
8290: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
82a0: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
82b0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
82c0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
82d0: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
82e0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
82f0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
8300: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
8310: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
8320: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
8330: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
8340: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
8350: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
8360: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
8370: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
8380: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61  )..**.** If xRea
8390: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  d() returns SQLI
83a0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
83b0: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f  EAD it must also
83c0: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20   fill.** in the 
83d0: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20  unread portions 
83e0: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69  of the buffer wi
83f0: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53  th zeros.  A VFS
8400: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74   that.** fails t
8410: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
8420: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65  t reads might se
8430: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77  em to work.  How
8440: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65  ever,.** failure
8450: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
8460: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65  ort reads will e
8470: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74  ventually lead t
8480: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  o.** database co
8490: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  rruption..*/.typ
84a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
84b0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
84c0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
84d0: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
84e0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
84f0: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
8500: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
8510: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
8520: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
8530: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
8540: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
8550: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8560: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
8570: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
8580: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
8590: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
85a0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
85b0: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74    int (*xTruncat
85c0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
85d0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
85e0: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
85f0: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
8600: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
8610: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
8620: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
8630: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8640: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
8650: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
8660: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
8670: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
8680: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8690: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
86a0: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
86b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
86c0: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
86d0: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
86e0: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
86f0: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
8700: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
8710: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
8720: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
8730: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
8740: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
8750: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
8760: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8770: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8780: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74  rsion 1 */.  int
8790: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69   (*xShmMap)(sqli
87a0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69  te3_file*, int i
87b0: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e  Pg, int pgsz, in
87c0: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65  t, void volatile
87d0: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  **);.  int (*xSh
87e0: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  mLock)(sqlite3_f
87f0: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74  ile*, int offset
8800: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61  , int n, int fla
8810: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53  gs);.  void (*xS
8820: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74  hmBarrier)(sqlit
8830: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8840: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71   (*xShmUnmap)(sq
8850: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8860: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20   deleteFlag);.  
8870: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
8880: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8890: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e  ersion 2 */.  in
88a0: 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69  t (*xFetch)(sqli
88b0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
88c0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
88d0: 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a  int iAmt, void *
88e0: 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  *pp);.  int (*xU
88f0: 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  nfetch)(sqlite3_
8900: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8910: 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64  nt64 iOfst, void
8920: 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f   *p);.  /* Metho
8930: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8940: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  id for version 3
8950: 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f   */.  /* Additio
8960: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20  nal methods may 
8970: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
8980: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d  re releases */.}
8990: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
89a0: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65  F: Standard File
89b0: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73   Control Opcodes
89c0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
89d0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
89e0: 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72  des} {file contr
89f0: 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a  ol opcode}.**.**
8a00: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
8a10: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
8a20: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
8a30: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8a40: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
8a50: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
8a60: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
8a70: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
8a80: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
8a90: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
8aa0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8ab0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
8ac0: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
8ad0: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
8ae0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
8af0: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
8b00: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
8b10: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
8b20: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
8b30: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
8b40: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
8b50: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
8b60: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
8b70: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
8b80: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
8b90: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
8ba0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
8bb0: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
8bc0: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
8bd0: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
8be0: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
8bf0: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
8c00: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
8c10: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ng and only need
8c20: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
8c30: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
8c40: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64  ST.** is defined
8c50: 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  ..** <ul>.** <li
8c60: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
8c70: 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54  SIZE_HINT]].** T
8c80: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8c90: 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f  _SIZE_HINT] opco
8ca0: 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51  de is used by SQ
8cb0: 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65  Lite to give the
8cc0: 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20   VFS.** layer a 
8cd0: 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67  hint of how larg
8ce0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
8cf0: 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f  ile will grow to
8d00: 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a   be during the.*
8d10: 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  * current transa
8d20: 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e  ction.  This hin
8d30: 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  t is not guarant
8d40: 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61  eed to be accura
8d50: 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20  te but it.** is 
8d60: 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68  often close.  Th
8d70: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53  e underlying VFS
8d80: 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f   might choose to
8d90: 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74   preallocate dat
8da0: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70  abase.** file sp
8db0: 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69  ace based on thi
8dc0: 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20  s hint in order 
8dd0: 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74  to help writes t
8de0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
8df0: 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65  * file run faste
8e00: 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  r..**.** <li>[[S
8e10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
8e20: 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  K_SIZE]].** The 
8e30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
8e40: 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65  UNK_SIZE] opcode
8e50: 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75   is used to requ
8e60: 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53  est that the VFS
8e70: 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20  .** extends and 
8e80: 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61  truncates the da
8e90: 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63  tabase file in c
8ea0: 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20  hunks of a size 
8eb0: 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
8ec0: 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f  the user. The fo
8ed0: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
8ee0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
8ef0: 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64  ontrol()] should
8f00: 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e   .** point to an
8f10: 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69   integer (type i
8f20: 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  nt) containing t
8f30: 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a  he new chunk-siz
8f40: 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20  e to use.** for 
8f50: 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61  the nominated da
8f60: 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69  tabase. Allocati
8f70: 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ng database file
8f80: 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a   space in large.
8f90: 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31  ** chunks (say 1
8fa0: 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d  MB at a time), m
8fb0: 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73  ay reduce file-s
8fc0: 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74  ystem fragmentat
8fd0: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f  ion and.** impro
8fe0: 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f  ve performance o
8ff0: 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a  n some systems..
9000: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9010: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
9020: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b  INTER]].** The [
9030: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
9040: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  E_POINTER] opcod
9050: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
9060: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
9070: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
9080: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
9090: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
90a0: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
90b0: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
90c0: 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c  n.  See the [sql
90d0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
90e0: 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  l()] documentati
90f0: 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  on for.** additi
9100: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
9110: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9120: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
9130: 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20  OMITTED]].** No 
9140: 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a  longer in use..*
9150: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9160: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a  E_FCNTL_SYNC]].*
9170: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9180: 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65  NTL_SYNC] opcode
9190: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
91a0: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69  ternally by SQLi
91b0: 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74  te and.** sent t
91c0: 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69  o the VFS immedi
91d0: 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65  ately before the
91e0: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73   xSync method is
91f0: 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a   invoked on a.**
9200: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64   database file d
9210: 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69  escriptor. Or, i
9220: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
9230: 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  od is not invoke
9240: 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68  d .** because th
9250: 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69  e user has confi
9260: 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74  gured SQLite wit
9270: 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79  h .** [PRAGMA sy
9280: 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47  nchronous | PRAG
9290: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f  MA synchronous=O
92a0: 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  FF] it is invoke
92b0: 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f  d in place .** o
92c0: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
92d0: 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65  od. In most case
92e0: 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61  s, the pointer a
92f0: 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77  rgument passed w
9300: 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65  ith.** this file
9310: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c  -control is NULL
9320: 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68  . However, if th
9330: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9340: 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a  is being synced.
9350: 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20  ** as part of a 
9360: 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63  multi-database c
9370: 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d  ommit, the argum
9380: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  ent points to a 
9390: 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
93a0: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
93b0: 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74  ing the transact
93c0: 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72  ions master-jour
93d0: 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56  nal file name. V
93e0: 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f  FSes that .** do
93f0: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
9400: 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c  ignal should sil
9410: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
9420: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
9430: 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c  ations .** shoul
9440: 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69  d not call [sqli
9450: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9460: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70  ()] with this op
9470: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
9480: 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74   may .** disrupt
9490: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f   the operation o
94a0: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
94b0: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  d VFSes that do 
94c0: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
94d0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
94e0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
94f0: 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20  ASETWO]].** The 
9500: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
9510: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f  MMIT_PHASETWO] o
9520: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
9530: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
9540: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73   SQLite.** and s
9550: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61  ent to the VFS a
9560: 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  fter a transacti
9570: 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d  on has been comm
9580: 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  itted immediatel
9590: 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20  y.** but before 
95a0: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
95b0: 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20  unlocked. VFSes 
95c0: 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64  that do not need
95d0: 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20   this signal.** 
95e0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
95f0: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
9600: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
9610: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
9620: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
9630: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
9640: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73  h this opcode as
9650: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69   doing so may di
9660: 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70  srupt the .** op
9670: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  eration of the s
9680: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
9690: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
96a0: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
96b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
96c0: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d  WIN32_AV_RETRY]]
96d0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
96e0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
96f0: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73  RETRY] opcode is
9700: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
9710: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20  re automatic.** 
9720: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64  retry counts and
9730: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63   intervals for c
9740: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20  ertain disk I/O 
9750: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74  operations for t
9760: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56  he.** windows [V
9770: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  FS] in order to 
9780: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65  provide robustne
9790: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e  ss in the presen
97a0: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69  ce of.** anti-vi
97b0: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42  rus programs.  B
97c0: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77  y default, the w
97d0: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20  indows VFS will 
97e0: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c  retry file read,
97f0: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20  .** file write, 
9800: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20  and file delete 
9810: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f  operations up to
9820: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20   10 times, with 
9830: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35  a delay.** of 25
9840: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65   milliseconds be
9850: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72  fore the first r
9860: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68  etry and with th
9870: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69  e delay increasi
9880: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69  ng.** by an addi
9890: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73  tional 25 millis
98a0: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68  econds with each
98b0: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72   subsequent retr
98c0: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  y.  This.** opco
98d0: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20  de allows these 
98e0: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72  two values (10 r
98f0: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69  etries and 25 mi
9900: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65  lliseconds of de
9910: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64  lay).** to be ad
9920: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c  justed.  The val
9930: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20  ues are changed 
9940: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65  for all database
9950: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
9960: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
9970: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72  process.  The ar
9980: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
9990: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20  ter to an array 
99a0: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65  of two.** intege
99b0: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72  rs where the fir
99c0: 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65  st integer i the
99d0: 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74   new retry count
99e0: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a   and the second.
99f0: 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68  ** integer is th
9a00: 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74  e delay.  If eit
9a10: 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e  her integer is n
9a20: 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
9a30: 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20  e setting.** is 
9a40: 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20  not changed but 
9a50: 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f  instead the prio
9a60: 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  r value of that 
9a70: 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74  setting is writt
9a80: 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61  en.** into the a
9a90: 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f  rray entry, allo
9aa0: 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74  wing the current
9ab0: 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20   retry settings 
9ac0: 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f  to be.** interro
9ad0: 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e  gated.  The zDbN
9ae0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
9af0: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
9b00: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9b10: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d  TL_PERSIST_WAL]]
9b20: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
9b30: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
9b40: 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  AL] opcode is us
9b50: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
9b60: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
9b70: 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74  tent [WAL | Writ
9b80: 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74  e Ahead Log] set
9b90: 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c  ting.  By defaul
9ba0: 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79  t, the auxiliary
9bb0: 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20  .** write ahead 
9bc0: 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d  log and shared m
9bd0: 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64  emory files used
9be0: 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e   for transaction
9bf0: 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20   control.** are 
9c00: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
9c10: 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c  leted when the l
9c20: 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e  atest connection
9c30: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
9c40: 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74  .** closes.  Set
9c50: 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20  ting persistent 
9c60: 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20  WAL mode causes 
9c70: 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70  those files to p
9c80: 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20  ersist after.** 
9c90: 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69  close.  Persisti
9ca0: 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20  ng the files is 
9cb0: 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65  useful when othe
9cc0: 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74  r processes that
9cd0: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20   do not.** have 
9ce0: 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e  write permission
9cf0: 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72   on the director
9d00: 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  y containing the
9d10: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
9d20: 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74  ant.** to read t
9d30: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9d40: 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64  , as the WAL and
9d50: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
9d60: 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a  iles must exist.
9d70: 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20  ** in order for 
9d80: 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20  the database to 
9d90: 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  be readable.  Th
9da0: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
9db0: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
9dc0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9dd0: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
9de0: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
9df0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
9e00: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
9e10: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
9e20: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20  able persistent 
9e30: 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  WAL mode or 1 to
9e40: 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65   enable persiste
9e50: 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20  nt.** WAL mode. 
9e60: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
9e70: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
9e80: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
9e90: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
9ea0: 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63  * WAL persistenc
9eb0: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
9ec0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9ed0: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
9ee0: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
9ef0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9f00: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
9f10: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ITE] opcode is u
9f20: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
9f30: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
9f40: 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65  stent "powersafe
9f50: 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22  -overwrite" or "
9f60: 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20  PSOW" setting.  
9f70: 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67  The PSOW setting
9f80: 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74  .** determines t
9f90: 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  he [SQLITE_IOCAP
9fa0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
9fb0: 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65  RITE] bit of the
9fc0: 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61  .** xDeviceChara
9fd0: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
9fe0: 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70  ds. The fourth p
9ff0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
a000: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
a010: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
a020: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
a030: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
a040: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
a050: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
a060: 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d  to disable zero-
a070: 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31  damage mode or 1
a080: 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d   to enable zero-
a090: 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20  damage.** mode. 
a0a0: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
a0b0: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
a0c0: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
a0d0: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
a0e0: 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  * zero-damage mo
a0f0: 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  de setting..**.*
a100: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a110: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d  CNTL_OVERWRITE]]
a120: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a130: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
a140: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f  ] opcode is invo
a150: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66  ked by SQLite af
a160: 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61  ter opening.** a
a170: 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69   write transacti
a180: 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  on to indicate t
a190: 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69  hat, unless it i
a1a0: 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f  s rolled back fo
a1b0: 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e  r some.** reason
a1c0: 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74  , the entire dat
a1d0: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
a1e0: 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62  be overwritten b
a1f0: 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a  y the current .*
a200: 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54  * transaction. T
a210: 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56  his is used by V
a220: 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73  ACUUM operations
a230: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a240: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
a250: 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ME]].** ^The [SQ
a260: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
a270: 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62  ME] opcode can b
a280: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
a290: 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a   the names of.**
a2a0: 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20   all [VFSes] in 
a2b0: 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20  the VFS stack.  
a2c0: 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66  The names are of
a2d0: 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61   all VFS shims a
a2e0: 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  nd the.** final 
a2f0: 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53  bottom-level VFS
a300: 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74   are written int
a310: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
a320: 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
a330: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
a340: 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  d the result is 
a350: 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68  stored in the ch
a360: 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  ar* variable.** 
a370: 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20  that the fourth 
a380: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71  parameter of [sq
a390: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
a3a0: 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e  ol()] points to.
a3b0: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69  .** The caller i
a3c0: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
a3d0: 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65  r freeing the me
a3e0: 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20  mory when done. 
a3f0: 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20   As with.** all 
a400: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74  file-control act
a410: 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e  ions, there is n
a420: 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  o guarantee that
a430: 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61   this will actua
a440: 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69  lly.** do anythi
a450: 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f  ng.  Callers sho
a460: 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74  uld initialize t
a470: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a480: 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  e to a NULL.** p
a490: 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74  ointer in case t
a4a0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a4b0: 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   is not implemen
a4c0: 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d  ted.  This file-
a4d0: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e  control.** is in
a4e0: 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e  tended for diagn
a4f0: 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a  ostic use only..
a500: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a510: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a520: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61  ].** ^Whenever a
a530: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
a540: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61  ent is parsed, a
a550: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  n [SQLITE_FCNTL_
a560: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65  PRAGMA] .** file
a570: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74   control is sent
a580: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71   to the open [sq
a590: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
a5a0: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ct corresponding
a5b0: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62  .** to the datab
a5c0: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63  ase file to whic
a5d0: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61  h the pragma sta
a5e0: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e  tement refers. ^
a5f0: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  The argument.** 
a600: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  to the [SQLITE_F
a610: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
a620: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20  e control is an 
a630: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e  array of.** poin
a640: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
a650: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63  (char**) in whic
a660: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65  h the second ele
a670: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61  ment of the arra
a680: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  y.** is the name
a690: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61   of the pragma a
a6a0: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65  nd the third ele
a6b0: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75  ment is the argu
a6c0: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70  ment to the.** p
a6d0: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66  ragma or NULL if
a6e0: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20   the pragma has 
a6f0: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  no argument.  ^T
a700: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  he handler for a
a710: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  n.** [SQLITE_FCN
a720: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
a730: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69  control can opti
a740: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20  onally make the 
a750: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a  first element.**
a760: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61   of the char** a
a770: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f  rgument point to
a780: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e   a string obtain
a790: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
a7a0: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f  _mprintf()].** o
a7b0: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
a7c0: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67   and that string
a7d0: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
a7e0: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70   result of the p
a7f0: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20  ragma or.** the 
a800: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66  error message if
a810: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c   the pragma fail
a820: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  s. ^If the.** [S
a830: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a840: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
a850: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
a860: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e  _NOTFOUND], then
a870: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41   normal .** [PRA
a880: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20  GMA] processing 
a890: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20  continues.  ^If 
a8a0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
a8b0: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
a8c0: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
a8d0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
a8e0: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61  hen the parser a
a8f0: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
a900: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c  ** VFS has handl
a910: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74  ed the PRAGMA it
a920: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72  self and the par
a930: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20  ser generates a 
a940: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65  no-op.** prepare
a950: 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49  d statement.  ^I
a960: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
a970: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
a980: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
a990: 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63  .** any result c
a9a0: 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ode other than [
a9b0: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53  SQLITE_OK] or [S
a9c0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a9d0: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
a9e0: 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f  hat the VFS enco
a9f0: 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72  untered an error
aa00: 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20   while handling 
aa10: 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64  the [PRAGMA] and
aa20: 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74   the.** compilat
aa30: 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d  ion of the PRAGM
aa40: 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20  A fails with an 
aa50: 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51  error.  ^The [SQ
aa60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
aa70: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
aa80: 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65  ol occurs at the
aa90: 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72   beginning of pr
aaa0: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61  agma statement a
aab0: 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a  nalysis and so.*
aac0: 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20  * it is able to 
aad0: 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69  override built-i
aae0: 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  n [PRAGMA] state
aaf0: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ments..**.** <li
ab00: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
ab10: 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a  BUSYHANDLER]].**
ab20: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
ab30: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
ab40: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
ab50: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
ab60: 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65  by SQLite on the
ab70: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68   database file h
ab80: 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79  andle.** shortly
ab90: 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65   after it is ope
aba0: 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ned in order to 
abb0: 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d  provide a custom
abc0: 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73   VFS with access
abd0: 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65  .** to the conne
abe0: 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64  ctions busy-hand
abf0: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68  ler callback. Th
ac00: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66  e argument is of
ac10: 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a   type (void **).
ac20: 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66  ** - an array of
ac30: 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61   two (void *) va
ac40: 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20  lues. The first 
ac50: 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c  (void *) actuall
ac60: 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61  y points.** to a
ac70: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
ac80: 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20  e (int (*)(void 
ac90: 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f  *)). In order to
aca0: 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e   invoke the conn
acb0: 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d  ections.** busy-
acc0: 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75  handler, this fu
acd0: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  nction should be
ace0: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68   invoked with th
acf0: 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a  e second (void *
ad00: 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61  ) in.** the arra
ad10: 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72  y as the only ar
ad20: 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65  gument. If it re
ad30: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
ad40: 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69  then the operati
ad50: 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
ad60: 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72  retried. If it r
ad70: 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
ad80: 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75   custom VFS shou
ad90: 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a  ld abandon the.*
ada0: 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  * current operat
adb0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ion..**.** <li>[
adc0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
add0: 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20  MPFILENAME]].** 
ade0: 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e  ^Application can
adf0: 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c   invoke the [SQL
ae00: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
ae10: 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e  LENAME] file-con
ae20: 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20  trol.** to have 
ae30: 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20  SQLite generate 
ae40: 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  a.** temporary f
ae50: 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68  ilename using th
ae60: 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
ae70: 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65   that is followe
ae80: 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a  d to generate.**
ae90: 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e   temporary filen
aea0: 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61  ames for TEMP ta
aeb0: 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69  bles and other i
aec0: 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54  nternal uses.  T
aed0: 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  he.** argument s
aee0: 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a  hould be a char*
aef0: 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20  * which will be 
af00: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
af10: 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74  filename.** writ
af20: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
af30: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
af40: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
af50: 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68  .  The caller sh
af60: 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b  ould.** invoke [
af70: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
af80: 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f  on the result to
af90: 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20   avoid a memory 
afa0: 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  leak..**.** <li>
afb0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d  [[SQLITE_FCNTL_M
afc0: 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68  MAP_SIZE]].** Th
afd0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
afe0: 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20  MMAP_SIZE] file 
aff0: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
b000: 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20  to query or set 
b010: 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e  the.** maximum n
b020: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74  umber of bytes t
b030: 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64  hat will be used
b040: 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70   for memory-mapp
b050: 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61  ed I/O..** The a
b060: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
b070: 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20  nter to a value 
b080: 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f  of type sqlite3_
b090: 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73  int64 that.** is
b0a0: 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78   an advisory max
b0b0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
b0c0: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
b0d0: 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20   to memory map. 
b0e0: 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   The.** pointer 
b0f0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
b100: 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75  ith the old valu
b110: 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73  e.  The limit is
b120: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a   not changed if.
b130: 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69  ** the value ori
b140: 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20  ginally pointed 
b150: 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  to is negative, 
b160: 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 65  and so the curre
b170: 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e  nt limit .** can
b180: 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20 70   be queried by p
b190: 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e  assing in a poin
b1a0: 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76  ter to a negativ
b1b0: 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a  e number.  This.
b1c0: 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ** file-control 
b1d0: 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
b1e0: 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ly to implement 
b1f0: 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
b200: 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  e]..**.** <li>[[
b210: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
b220: 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  CE]].** The [SQL
b230: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
b240: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72   file control pr
b250: 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79 20  ovides advisory 
b260: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74  information.** t
b270: 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74 20  o the VFS about 
b280: 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72 20  what the higher 
b290: 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53 51  layers of the SQ
b2a0: 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20 64  Lite stack are d
b2b0: 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69  oing..** This fi
b2c0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le control is us
b2d0: 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61  ed by some VFS a
b2e0: 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67 20  ctivity tracing 
b2f0: 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20  [shims]..** The 
b300: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65  argument is a ze
b310: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
b320: 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61  ring.  Higher la
b330: 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53  yers in the.** S
b340: 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20  QLite stack may 
b350: 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63  generate instanc
b360: 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  es of this file 
b370: 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68  control if.** th
b380: 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43  e [SQLITE_USE_FC
b390: 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69  NTL_TRACE] compi
b3a0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
b3b0: 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
b3c0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b3d0: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a  NTL_HAS_MOVED]].
b3e0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
b3f0: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20  CNTL_HAS_MOVED] 
b400: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74  file control int
b410: 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67 75  erprets its argu
b420: 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69  ment as a.** poi
b430: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
b440: 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65 73  er and it writes
b450: 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20   a boolean into 
b460: 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65 70  that integer dep
b470: 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65  ending.** on whe
b480: 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
b490: 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65  file has been re
b4a0: 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72  named, moved, or
b4b0: 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69   deleted since i
b4c0: 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f  t.** was first o
b4d0: 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  pened..**.** <li
b4e0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b4f0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
b500: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b510: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45  E_FCNTL_WIN32_SE
b520: 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65  T_HANDLE] opcode
b530: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
b540: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
b550: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
b560: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
b570: 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74  method to swap t
b580: 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77  he file handle w
b590: 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70  ith the one.** p
b5a0: 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
b5b0: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20   pArg argument. 
b5c0: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
b5d0: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
b5e0: 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f  testing.** and o
b5f0: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20  nly needs to be 
b600: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53  supported when S
b610: 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64 65  QLITE_TEST is de
b620: 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75  fined..**.** </u
b630: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
b640: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
b650: 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  TATE            
b660: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
b670: 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_GET_LOCKPROX
b680: 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20  YFILE           
b690: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
b6a0: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_SET_LOCKPROXY
b6b0: 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  FILE            
b6c0: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
b6d0: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  E_LAST_ERRNO    
b6e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
b6f0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
b700: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
b710: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
b720: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b730: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
b740: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
b750: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b760: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
b770: 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23  R            7.#
b780: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b790: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
b7a0: 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64              8.#d
b7b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b7c0: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
b7d0: 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65  Y          9.#de
b7e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b7f0: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20  L_PERSIST_WAL   
b800: 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
b810: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b820: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20  _OVERWRITE      
b830: 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69          11.#defi
b840: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b850: 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20  VFSNAME         
b860: 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e         12.#defin
b870: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
b880: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
b890: 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65  TE    13.#define
b8a0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52   SQLITE_FCNTL_PR
b8b0: 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
b8c0: 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20       14.#define 
b8d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
b8e0: 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20  YHANDLER        
b8f0: 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53      15.#define S
b900: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
b910: 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20  FILENAME        
b920: 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
b930: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
b940: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
b950: 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c    18.#define SQL
b960: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20  ITE_FCNTL_TRACE 
b970: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
b980: 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   19.#define SQLI
b990: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
b9a0: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
b9b0: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
b9c0: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20  E_FCNTL_SYNC    
b9d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
b9e0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
b9f0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
ba00: 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32  ASETWO        22
ba10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ba20: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
ba30: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a  HANDLE       23.
ba40: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ba50: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
ba60: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
ba70: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
ba80: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
ba90: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
baa0: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
bab0: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
bac0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
bad0: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
bae0: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
baf0: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
bb00: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
bb10: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
bb20: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
bb30: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
bb40: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
bb50: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
bb60: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
bb70: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
bb80: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
bb90: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
bba0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
bbb0: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
bbc0: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
bbd0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
bbe0: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
bbf0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
bc00: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
bc10: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
bc20: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
bc30: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
bc40: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
bc50: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
bc60: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
bc70: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
bc80: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
bc90: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
bca0: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
bcb0: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
bcc0: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
bcd0: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
bce0: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
bcf0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
bd00: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
bd10: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
bd20: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
bd30: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
bd40: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
bd50: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
bd60: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
bd70: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
bd80: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
bd90: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
bda0: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
bdb0: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
bdc0: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
bdd0: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
bde0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
bdf0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
be00: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
be10: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
be20: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
be30: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
be40: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
be50: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
be60: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
be70: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
be80: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
be90: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
bea0: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
beb0: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
bec0: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
bed0: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
bee0: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
bef0: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
bf00: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
bf10: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
bf20: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
bf30: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
bf40: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
bf50: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
bf60: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
bf70: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
bf80: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
bf90: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
bfa0: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
bfb0: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
bfc0: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
bfd0: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
bfe0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
bff0: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
c000: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
c010: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
c020: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
c030: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
c040: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
c050: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
c060: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
c070: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
c080: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
c090: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
c0a0: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
c0b0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
c0c0: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
c0d0: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
c0e0: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
c0f0: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
c100: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
c110: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
c120: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
c130: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
c140: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
c150: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
c160: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
c170: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
c180: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
c190: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
c1a0: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
c1b0: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
c1c0: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
c1d0: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
c1e0: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
c1f0: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
c200: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
c210: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  s..**.** [[sqlit
c220: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a  e3_vfs.xOpen]].*
c230: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
c240: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46  tees that the zF
c250: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
c260: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
c270: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
c280: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
c290: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
c2a0: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
c2b0: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e  ) with an option
c2c0: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e  al suffix added.
c2d0: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78  .** ^If a suffix
c2e0: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
c2f0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
c300: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a  eter, it will.**
c310: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69   consist of a si
c320: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74  ngle "-" charact
c330: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e  er followed by n
c340: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31  o more than.** 1
c350: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61  1 alphanumeric a
c360: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63  nd/or "-" charac
c370: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ters..** ^SQLite
c380: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
c390: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
c3a0: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
c3b0: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
c3c0: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
c3d0: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
c3e0: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
c3f0: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
c400: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
c410: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
c420: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
c430: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
c440: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
c450: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
c460: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
c470: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
c480: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
c490: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
c4a0: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
c4b0: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
c4c0: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69  ** must invent i
c4d0: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
c4e0: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
c4f0: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74  le.  ^Whenever t
c500: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
c510: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
c520: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
c530: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
c540: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
c550: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
c560: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
c570: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
c580: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
c590: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
c5a0: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
c5b0: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
c5c0: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
c5d0: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
c5e0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
c5f0: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
c600: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
c610: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
c620: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
c630: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
c640: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
c650: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
c660: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
c670: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
c680: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
c690: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
c6a0: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
c6b0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
c6c0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
c6d0: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
c6e0: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
c6f0: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
c700: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
c710: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
c720: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
c730: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
c740: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
c750: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
c760: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
c770: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
c780: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
c790: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
c7a0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c7b0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
c7c0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
c7d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
c7e0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
c7f0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
c800: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
c810: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
c820: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
c830: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
c840: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
c850: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c860: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
c870: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
c880: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a  LITE_OPEN_WAL].*
c890: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
c8a0: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
c8b0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
c8c0: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
c8d0: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
c8e0: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
c8f0: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
c900: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
c910: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
c920: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
c930: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
c940: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
c950: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
c960: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
c970: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
c980: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
c990: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
c9a0: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
c9b0: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
c9c0: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
c9d0: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
c9e0: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
c9f0: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
ca00: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
ca10: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
ca20: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
ca30: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
ca40: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
ca50: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
ca60: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
ca70: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
ca80: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
ca90: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
caa0: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
cab0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
cac0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
cad0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
cae0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
caf0: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
cb00: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
cb10: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
cb20: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
cb30: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
cb40: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
cb50: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  >.**.** The [SQL
cb60: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
cb70: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
cb80: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
cb90: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
cba0: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
cbb0: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ed.  ^The [SQLIT
cbc0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
cbd0: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
cbe0: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61   set for TEMP da
cbf0: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69  tabases and thei
cc00: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e  r journals, tran
cc10: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73  sient.** databas
cc20: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e  es, and subjourn
cc30: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  als..**.** ^The 
cc40: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
cc50: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20  LUSIVE] flag is 
cc60: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63  always used in c
cc70: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  onjunction.** wi
cc80: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
cc90: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67  PEN_CREATE] flag
cca0: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68  , which are both
ccb0: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61   directly.** ana
ccc0: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f  logous to the O_
ccd0: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54  EXCL and O_CREAT
cce0: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f   flags of the PO
ccf0: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50  SIX open().** AP
cd00: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  I.  The SQLITE_O
cd10: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c  PEN_EXCLUSIVE fl
cd20: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20  ag, when paired 
cd30: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
cd40: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c  ITE_OPEN_CREATE,
cd50: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69   is used to indi
cd60: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73  cate that file s
cd70: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20  hould always.** 
cd80: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20  be created, and 
cd90: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72  that it is an er
cda0: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64  ror if it alread
cdb0: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20  y exists..** It 
cdc0: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73  is <i>not</i> us
cdd0: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
cde0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
cdf0: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72  e opened .** for
ce00: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
ce10: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61  s..**.** ^At lea
ce20: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
ce30: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
ce40: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
ce50: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
ce60: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
ce70: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
ce80: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
ce90: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
cea0: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65  xOpen.  The xOpe
ceb0: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
cec0: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
ced0: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
cee0: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
cef0: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20  ust fill it in. 
cf00: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68   Note that.** th
cf10: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d  e xOpen method m
cf20: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69  ust set the sqli
cf30: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
cf40: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61  s to either.** a
cf50: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f   valid [sqlite3_
cf60: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
cf70: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20  ct or to NULL.  
cf80: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a  xOpen must do.**
cf90: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68   this even if th
cfa0: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53  e open fails.  S
cfb0: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68  QLite expects th
cfc0: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  at the sqlite3_f
cfd0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20  ile.pMethods.** 
cfe0: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  element will be 
cff0: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65  valid after xOpe
d000: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64  n returns regard
d010: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
d020: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72  ess.** or failur
d030: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63  e of the xOpen c
d040: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  all..**.** [[sql
d050: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73  ite3_vfs.xAccess
d060: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73  ]].** ^The flags
d070: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
d080: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
d090: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
d0a0: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
d0b0: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
d0c0: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
d0d0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
d0e0: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
d0f0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
d100: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
d110: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
d120: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
d130: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
d140: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
d150: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
d160: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
d170: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
d180: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53  ectory..**.** ^S
d190: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
d1a0: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
d1b0: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
d1c0: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
d1d0: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
d1e0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
d1f0: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
d200: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
d210: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
d220: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
d230: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
d240: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
d250: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
d260: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
d270: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
d280: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
d290: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
d2a0: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
d2b0: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
d2c0: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
d2d0: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
d2e0: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
d2f0: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
d300: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
d310: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
d320: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
d330: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
d340: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
d350: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43  (), xSleep(), xC
d360: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e  urrentTime(), an
d370: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  d xCurrentTimeIn
d380: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  t64().** interfa
d390: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69  ces are not stri
d3a0: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
d3b0: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
d3c0: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
d3d0: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
d3e0: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
d3f0: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
d400: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
d410: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
d420: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
d430: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
d440: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
d450: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
d460: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
d470: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
d480: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
d490: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
d4a0: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
d4b0: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
d4c0: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
d4d0: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
d4e0: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
d4f0: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
d500: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
d510: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54  conds given.  ^T
d520: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
d530: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
d540: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
d550: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
d560: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
d570: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c   time as.** a fl
d580: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
d590: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72  ue..** ^The xCur
d5a0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
d5b0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
d5c0: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
d5d0: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
d5e0: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69   Number multipli
d5f0: 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28  ed by 86400000 (
d600: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
d610: 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a  lliseconds in .*
d620: 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29  * a 24-hour day)
d630: 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .  .** ^SQLite w
d640: 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72  ill use the xCur
d650: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
d660: 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68  method to get th
d670: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74  e current.** dat
d680: 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68  e and time if th
d690: 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61  at method is ava
d6a0: 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73  ilable (if iVers
d6b0: 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20  ion is 2 or .** 
d6c0: 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20  greater and the 
d6d0: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
d6e0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e   is not NULL) an
d6f0: 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b  d will fall back
d700: 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54  .** to xCurrentT
d710: 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e  ime() if xCurren
d720: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20  tTimeInt64() is 
d730: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a  unavailable..**.
d740: 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74  ** ^The xSetSyst
d750: 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79  emCall(), xGetSy
d760: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20  stemCall(), and 
d770: 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28  xNestSystemCall(
d780: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
d790: 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20  are not used by 
d7a0: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e  the SQLite core.
d7b0: 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c    These optional
d7c0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
d7d0: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73  provided.** by s
d7e0: 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63  ome VFSes to fac
d7f0: 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20  ilitate testing 
d800: 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e  of the VFS code.
d810: 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a   By overriding .
d820: 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  ** system calls 
d830: 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75  with functions u
d840: 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c  nder its control
d850: 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d  , a test program
d860: 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65   can.** simulate
d870: 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f   faults and erro
d880: 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61  r conditions tha
d890: 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73  t would otherwis
d8a0: 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a  e be difficult.*
d8b0: 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20  * or impossible 
d8c0: 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20  to induce.  The 
d8d0: 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61  set of system ca
d8e0: 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  lls that can be 
d8f0: 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61  overridden.** va
d900: 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46  ries from one VF
d910: 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e  S to another, an
d920: 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69  d from one versi
d930: 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56  on of the same V
d940: 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78  FS to the.** nex
d950: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
d960: 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20   that use these 
d970: 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20  interfaces must 
d980: 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20  be prepared for 
d990: 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66  any.** or all of
d9a0: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
d9b0: 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20  s to be NULL or 
d9c0: 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69  for their behavi
d9d0: 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  or to change.** 
d9e0: 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65  from one release
d9f0: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41   to the next.  A
da00: 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
da10: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20   not attempt to 
da20: 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66  access.** any of
da30: 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69   these methods i
da40: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f  f the iVersion o
da50: 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73  f the VFS is les
da60: 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70  s than 3..*/.typ
da70: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
da80: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
da90: 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69  vfs;.typedef voi
daa0: 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63  d (*sqlite3_sysc
dab0: 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a  all_ptr)(void);.
dac0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
dad0: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
dae0: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
daf0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
db00: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
db10: 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69  rently 3) */.  i
db20: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
db30: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
db40: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
db50: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
db60: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
db70: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
db80: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
db90: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
dba0: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
dbb0: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
dbc0: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
dbd0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
dbe0: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
dbf0: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
dc00: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
dc10: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
dc20: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
dc30: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
dc40: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
dc50: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
dc60: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
dc70: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
dc80: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
dc90: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
dca0: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
dcb0: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
dcc0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
dcd0: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
dce0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
dcf0: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
dd00: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
dd10: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
dd20: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
dd30: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
dd40: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
dd50: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
dd60: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
dd70: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
dd80: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
dd90: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
dda0: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
ddb0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
ddc0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
ddd0: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
dde0: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
ddf0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
de00: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
de10: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
de20: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
de30: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
de40: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
de50: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
de60: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
de70: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
de80: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
de90: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
dea0: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
deb0: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
dec0: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
ded0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
dee0: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
def0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
df00: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
df10: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
df20: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
df30: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
df40: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
df50: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
df60: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
df70: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
df80: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
df90: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
dfa0: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
dfb0: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
dfc0: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
dfd0: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
dfe0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
dff0: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
e000: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
e010: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
e020: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
e030: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
e040: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
e050: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
e060: 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62  ct..  ** Those b
e070: 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72  elow are for ver
e080: 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74  sion 3 and great
e090: 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  er..  */.  int (
e0a0: 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xSetSystemCall)
e0b0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
e0c0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
e0d0: 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  , sqlite3_syscal
e0e0: 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65  l_ptr);.  sqlite
e0f0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a  3_syscall_ptr (*
e100: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xGetSystemCall)(
e110: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e120: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
e130: 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ;.  const char *
e140: 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c  (*xNextSystemCal
e150: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
e160: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
e170: 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  me);.  /*.  ** T
e180: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
e190: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
e1a0: 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20   1 through 3 of 
e1b0: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
e1c0: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20  bject..  ** New 
e1d0: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
e1e0: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65  pended in figure
e1f0: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
e200: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
e210: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
e220: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
e230: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a   happens. .  */.
e240: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
e250: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
e260: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
e270: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
e280: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
e290: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
e2a0: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
e2b0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
e2c0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
e2d0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
e2e0: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
e2f0: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
e300: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
e310: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
e320: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
e330: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
e340: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
e350: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
e360: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
e370: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
e380: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
e390: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
e3a0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
e3b0: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
e3c0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
e3d0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e  ks whether the n
e3e0: 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69  amed directory i
e3f0: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
e400: 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20  and writable.** 
e410: 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  (in other words,
e420: 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65   if files can be
e430: 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c   added, removed,
e440: 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74   and renamed wit
e450: 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63  hin.** the direc
e460: 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51  tory)..** The SQ
e470: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
e480: 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69  WRITE constant i
e490: 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64  s currently used
e4a0: 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20   only by the.** 
e4b0: 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
e4c0: 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74  ctory pragma], t
e4d0: 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64  hough this could
e4e0: 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
e4f0: 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
e500: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74  f SQLite..** Wit
e510: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
e520: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
e530: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
e540: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
e550: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
e560: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43    The SQLITE_ACC
e570: 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e  ESS_READ constan
e580: 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c  t is.** currentl
e590: 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68  y unused, though
e5a0: 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65   it might be use
e5b0: 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  d in a future re
e5c0: 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
e5d0: 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
e5e0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
e5f0: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
e600: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
e610: 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20  EADWRITE 1   /* 
e620: 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74  Used by PRAGMA t
e630: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
e640: 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ory */.#define S
e650: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
e660: 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e  D      2   /* Un
e670: 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
e680: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
e690: 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  or the xShmLock 
e6a0: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
e6b0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
e6c0: 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
e6d0: 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b  the various lock
e6e0: 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ing operations.*
e6f0: 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65  * allowed by the
e700: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
e710: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   of [sqlite3_io_
e720: 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a  methods].  The.*
e730: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20  * following are 
e740: 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63  the only legal c
e750: 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66  ombinations of f
e760: 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  lags to the.** x
e770: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a  ShmLock method:.
e780: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
e790: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
e7a0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
e7b0: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
e7c0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
e7d0: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
e7e0: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CLUSIVE.** <li> 
e7f0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
e800: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
e810: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
e820: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
e830: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
e840: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c  XCLUSIVE.** </ul
e850: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c  >.**.** When unl
e860: 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65  ocking, the same
e870: 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55   SHARED or EXCLU
e880: 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62  SIVE flag must b
e890: 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a  e supplied as.**
e8a0: 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68   was given no th
e8b0: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
e8c0: 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  lock.  .**.** Th
e8d0: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
e8e0: 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e  d can transition
e8f0: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
e900: 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a  d and SHARED or.
e910: 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  ** between unloc
e920: 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56  ked and EXCLUSIV
e930: 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72  E.  It cannot tr
e940: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
e950: 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45   SHARED.** and E
e960: 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65  XCLUSIVE..*/.#de
e970: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
e980: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23  UNLOCK       1.#
e990: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
e9a0: 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32  M_LOCK         2
e9b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e9c0: 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20  SHM_SHARED      
e9d0: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
e9e0: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20  E_SHM_EXCLUSIVE 
e9f0: 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     8../*.** CAPI
ea00: 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53  3REF: Maximum xS
ea10: 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a  hmLock index.**.
ea20: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
ea30: 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74  method on [sqlit
ea40: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d  e3_io_methods] m
ea50: 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a  ay use values.**
ea60: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
ea70: 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20  his upper bound 
ea80: 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20  as its "offset" 
ea90: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
eaa0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
eab0: 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20  l never attempt 
eac0: 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65  to acquire or re
ead0: 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20  lease a.** lock 
eae0: 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20  outside of this 
eaf0: 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65  range.*/.#define
eb00: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43   SQLITE_SHM_NLOC
eb10: 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  K        8.../*.
eb20: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69  ** CAPI3REF: Ini
eb30: 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69  tialize The SQLi
eb40: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
eb50: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
eb60: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
eb70: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
eb80: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
eb90: 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69  rary.  ^The sqli
eba0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
ebb0: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
ebc0: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
ebd0: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
ebe0: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
ebf0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
ec00: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
ec10: 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20  es are designed 
ec20: 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73  to aid in proces
ec30: 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
ec40: 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e   and.** shutdown
ec50: 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73   on embedded sys
ec60: 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69  tems.  Workstati
ec70: 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  on applications 
ec80: 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20  using.** SQLite 
ec90: 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20  normally do not 
eca0: 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65  need to invoke e
ecb0: 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72  ither of these r
ecc0: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  outines..**.** A
ecd0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
ece0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
ecf0: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
ed00: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a  call if it is.**
ed10: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
ed20: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ed30: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ze() is invoked 
ed40: 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
ed50: 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72  ime of.** the pr
ed60: 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20  ocess, or if it 
ed70: 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  is the first tim
ed80: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
ed90: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
eda0: 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  d.** following a
edb0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
edc0: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28  _shutdown().  ^(
edd0: 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76  Only an effectiv
ede0: 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c  e call.** of sql
edf0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ee00: 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69  ) does any initi
ee10: 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20  alization.  All 
ee20: 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61  other calls.** a
ee30: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
ee40: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ps.)^.**.** A ca
ee50: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
ee60: 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22  utdown() is an "
ee70: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
ee80: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
ee90: 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  st.** call to sq
eea0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
eeb0: 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
eec0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
eed0: 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a  ze().  ^(Only.**
eee0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
eef0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
ef00: 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e  utdown() does an
ef10: 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69  y deinitializati
ef20: 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72  on..** All other
ef30: 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20   valid calls to 
ef40: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ef50: 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  () are harmless 
ef60: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
ef70: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
ef80: 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61  ialize() interfa
ef90: 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ce is threadsafe
efa0: 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68  , but sqlite3_sh
efb0: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e  utdown().** is n
efc0: 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ot.  The sqlite3
efd0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65  _shutdown() inte
efe0: 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20  rface must only 
eff0: 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  be called from a
f000: 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61  .** single threa
f010: 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61  d.  All open [da
f020: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f030: 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73  ns] must be clos
f040: 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74  ed and all.** ot
f050: 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75  her SQLite resou
f060: 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61  rces must be dea
f070: 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74  llocated prior t
f080: 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71  o invoking.** sq
f090: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f0a0: 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74  ..**.** Among ot
f0b0: 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c  her things, ^sql
f0c0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f0d0: 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a  ) will invoke.**
f0e0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f0f0: 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20  ().  Similarly, 
f100: 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  ^sqlite3_shutdow
f110: 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f  n().** will invo
f120: 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ke sqlite3_os_en
f130: 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  d()..**.** ^The 
f140: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f150: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
f160: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
f170: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
f180: 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ^If for some rea
f190: 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
f1a0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
f1b0: 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
f1c0: 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
f1d0: 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
f1e0: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
f1f0: 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
f200: 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
f210: 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
f220: 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
f230: 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
f240: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
f250: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
f260: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
f270: 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
f280: 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
f290: 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
f2a0: 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
f2b0: 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
f2c0: 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
f2d0: 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
f2e0: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
f2f0: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
f300: 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
f310: 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
f320: 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
f330: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f340: 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
f350: 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
f360: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
f370: 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
f380: 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
f390: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
f3a0: 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
f3b0: 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
f3c0: 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c  eady.  ^However,
f3d0: 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
f3e0: 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
f3f0: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
f400: 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  OINIT].** compil
f410: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74  e-time option, t
f420: 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69  hen the automati
f430: 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  c calls to sqlit
f440: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
f450: 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61  ** are omitted a
f460: 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
f470: 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c  on must call sql
f480: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f490: 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72  ) directly.** pr
f4a0: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
f4b0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
f4c0: 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61  terface.  For ma
f4d0: 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74  ximum portabilit
f4e0: 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f  y,.** it is reco
f4f0: 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
f500: 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73  lications always
f510: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
f520: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
f530: 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74  directly prior t
f540: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
f550: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
f560: 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65  ce.  Future rele
f570: 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ases.** of SQLit
f580: 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68  e may require th
f590: 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  is.  In other wo
f5a0: 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f  rds, the behavio
f5b0: 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77  r exhibited.** w
f5c0: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
f5d0: 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
f5e0: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
f5f0: 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20  T] might become 
f600: 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62  the.** default b
f610: 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20  ehavior in some 
f620: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
f630: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
f640: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
f650: 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  nit() routine do
f660: 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  es operating-sys
f670: 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  tem specific.** 
f680: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
f690: 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
f6a0: 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
f6b0: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72  e3_os_end().** r
f6c0: 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68  outine undoes th
f6d0: 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69  e effect of sqli
f6e0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
f6f0: 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a  Typical tasks.**
f700: 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68   performed by th
f710: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63  ese routines inc
f720: 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  lude allocation 
f730: 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  or deallocation.
f740: 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73  ** of static res
f750: 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69  ources, initiali
f760: 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c  zation of global
f770: 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73   variables,.** s
f780: 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61  etting up a defa
f790: 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
f7a0: 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74  ] module, or set
f7b0: 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66  ting up.** a def
f7c0: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
f7d0: 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  on using [sqlite
f7e0: 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a  3_config()]..**.
f7f0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
f800: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
f810: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71  invoke either sq
f820: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
f830: 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  ** or sqlite3_os
f840: 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e  _end() directly.
f850: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
f860: 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e  n should only in
f870: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
f880: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
f890: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f8a0: 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65  n().  The sqlite
f8b0: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69  3_os_init().** i
f8c0: 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c  nterface is call
f8d0: 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
f8e0: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
f8f0: 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20  ialize() and.** 
f900: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
f910: 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71   is called by sq
f920: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f930: 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a  .  Appropriate.*
f940: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
f950: 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  s for sqlite3_os
f960: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
f970: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
f980: 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  are built into S
f990: 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73  QLite when it is
f9a0: 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e   compiled for Un
f9b0: 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20  ix, Windows, or 
f9c0: 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63  OS/2..** When [c
f9d0: 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62  ustom builds | b
f9e0: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
f9f0: 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73  latforms].** (us
fa00: 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
fa10: 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70  OS_OTHER=1] comp
fa20: 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
fa30: 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
fa40: 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
fa50: 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
fa60: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
fa70: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
fa80: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
fa90: 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
faa0: 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
fab0: 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
fac0: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
fad0: 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
fae0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
faf0: 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c  must return [SQL
fb00: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
fb10: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
fb20: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
fb30: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
fb40: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69  */.int sqlite3_i
fb50: 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
fb60: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75  .int sqlite3_shu
fb70: 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74  tdown(void);.int
fb80: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
fb90: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
fba0: 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
fbb0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
fbc0: 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
fbd0: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
fbe0: 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  y.**.** The sqli
fbf0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
fc00: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
fc10: 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f  o make global co
fc20: 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
fc30: 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65  hanges to SQLite
fc40: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e   in order to tun
fc50: 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  e SQLite to the 
fc60: 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
fc70: 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
fc80: 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75  tion.  The defau
fc90: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
fca0: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
fcb0: 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c  for most.** appl
fcc0: 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20  ications and so 
fcd0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
fce0: 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65  usually not nece
fcf0: 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a  ssary.  It is.**
fd00: 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70   provided to sup
fd10: 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63  port rare applic
fd20: 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73  ations with unus
fd30: 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ual needs..**.**
fd40: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
fd50: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
fd60: 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66  is not threadsaf
fd70: 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  e.  The applicat
fd80: 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75  ion.** must insu
fd90: 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72  re that no other
fda0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
fdb0: 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62  es are invoked b
fdc0: 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61  y other.** threa
fdd0: 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  ds while sqlite3
fde0: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e  _config() is run
fdf0: 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f  ning.  Furthermo
fe00: 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  re, sqlite3_conf
fe10: 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ig().** may only
fe20: 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   be invoked prio
fe30: 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69  r to library ini
fe40: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e  tialization usin
fe50: 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  g.** [sqlite3_in
fe60: 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  itialize()] or a
fe70: 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79  fter shutdown by
fe80: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
fe90: 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  wn()]..** ^If sq
fea0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
feb0: 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  s called after [
fec0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fed0: 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65  ze()] and before
fee0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
fef0: 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74  tdown()] then it
ff00: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c   will return SQL
ff10: 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e  ITE_MISUSE..** N
ff20: 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
ff30: 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66  at ^sqlite3_conf
ff40: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
ff50: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
ff60: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
ff70: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
ff80: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
ff90: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
ffa0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
ffb0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
ffc0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
ffd0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
ffe0: 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
fff0: 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
10000 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
10010 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
10020 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
10030 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
10040 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
10050 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
10060 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72  on the [configur
10070 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
10080 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
10090 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
100a0 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
100b0 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
100c0 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
100d0 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
100e0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
100f0 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
10100 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
10110 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
10120 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
10130 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
10140 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
10150 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
10160 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
10170 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
10180 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10190 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
101a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
101b0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ns.**.** The sql
101c0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
101d0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
101e0 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
101f0 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
10200 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
10210 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
10220 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
10230 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
10240 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10250 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
10260 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
10270 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
10280 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10290 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
102a0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
102b0 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** T
102c0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
102d0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
102e0 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
102f0 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
10300 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
10310 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
10320 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
10330 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
10340 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
10350 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
10360 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
10370 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
10380 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
10390 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
103a0 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
103b0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
103c0 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
103d0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
103e0 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
103f0 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
10400 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
10410 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
10420 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
10430 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69  successful..*/.i
10440 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
10450 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
10460 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
10470 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
10480 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
10490 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
104a0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
104b0 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
104c0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
104d0 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
104e0 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
104f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10500 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
10510 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
10520 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
10530 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
10540 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
10550 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
10560 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
10570 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
10580 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
10590 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
105a0 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
105b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
105c0 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
105d0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
105e0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
105f0 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
10600 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
10610 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
10620 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
10630 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
10640 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
10650 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
10660 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
10670 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
10680 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
10690 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
106a0 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
106b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
106c0 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
106d0 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
106e0 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
106f0 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
10700 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
10710 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
10720 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
10730 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
10740 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
10750 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
10760 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
10770 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
10780 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
10790 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
107a0 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
107b0 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
107c0 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
107d0 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
107e0 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
107f0 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
10800 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
10810 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
10820 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
10830 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
10840 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
10850 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
10860 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
10870 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
10880 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
10890 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
108a0 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
108b0 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
108c0 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
108d0 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
108e0 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
108f0 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
10900 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
10910 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
10920 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
10930 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
10940 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
10950 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
10960 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
10970 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
10980 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
10990 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
109a0 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
109b0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
109c0 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
109d0 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
109e0 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
109f0 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
10a00 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
10a10 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
10a20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
10a30 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
10a40 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
10a50 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
10a60 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
10a70 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
10a80 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
10a90 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
10aa0 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
10ab0 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
10ac0 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
10ad0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
10ae0 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
10af0 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
10b00 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
10b10 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
10b20 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
10b30 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
10b40 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
10b50 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
10b60 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
10b70 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
10b80 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
10b90 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
10ba0 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
10bb0 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
10bc0 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
10bd0 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
10be0 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
10bf0 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
10c00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
10c10 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
10c20 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
10c30 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
10c40 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
10c50 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
10c60 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
10c70 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
10c80 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
10c90 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
10ca0 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
10cb0 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
10cc0 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
10cd0 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
10ce0 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
10cf0 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61  ocator.  For exa
10d00 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
10d10 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
10d20 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
10d30 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
10d40 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
10d50 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
10d60 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
10d70 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
10d80 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
10d90 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10da0 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
10db0 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
10dc0 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
10dd0 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
10de0 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
10df0 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
10e00 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
10e10 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
10e20 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
10e30 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
10e40 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
10e50 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
10e60 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
10e70 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
10e80 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
10e90 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
10ea0 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
10eb0 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
10ec0 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
10ed0 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
10ee0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
10ef0 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
10f00 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
10f10 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
10f20 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
10f30 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
10f40 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
10f50 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
10f60 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
10f70 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
10f80 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
10f90 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
10fa0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10fb0 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
10fc0 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
10fd0 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
10fe0 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
10ff0 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
11000 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
11010 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
11020 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
11030 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
11040 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
11050 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
11060 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
11070 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
11080 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
11090 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
110a0 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
110b0 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
110c0 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
110d0 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
110e0 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
110f0 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
11100 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
11110 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
11120 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
11130 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
11140 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
11150 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
11160 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
11170 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
11180 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
11190 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
111a0 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
111b0 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
111c0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
111d0 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
111e0 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
111f0 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
11200 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
11210 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
11220 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
11230 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
11240 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
11250 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
11260 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
11270 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
11280 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
11290 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
112a0 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
112b0 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
112c0 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
112d0 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
112e0 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
112f0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
11300 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
11310 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
11320 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
11330 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
11340 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
11350 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
11360 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
11370 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
11380 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
11390 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
113a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
113b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
113c0 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
113d0 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
113e0 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
113f0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
11400 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
11410 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
11420 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
11430 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
11440 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
11450 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
11460 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11470 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
11480 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
11490 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
114a0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
114b0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
114c0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
114d0 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
114e0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
114f0 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
11500 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
11510 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
11520 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
11530 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
11540 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
11550 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
11560 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
11570 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
11580 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
11590 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
115a0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
115b0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
115c0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
115d0 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
115e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
115f0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
11600 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
11610 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
11620 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
11630 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
11640 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
11650 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
11660 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
11670 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
11680 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
11690 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
116a0 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
116b0 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
116c0 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
116d0 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
116e0 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
116f0 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
11700 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
11710 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
11720 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
11730 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
11740 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
11750 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
11760 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
11770 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
11780 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
11790 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
117a0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
117b0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
117c0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
117d0 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
117e0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
117f0 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
11800 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
11810 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
11820 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
11830 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
11840 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
11850 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
11860 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
11870 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
11880 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11890 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
118a0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
118b0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
118c0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
118d0 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
118e0 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
118f0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
11900 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
11910 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11920 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
11930 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
11940 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
11950 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
11960 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11970 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
11980 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
11990 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
119a0 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
119b0 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
119c0 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
119d0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
119e0 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
119f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
11a00 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
11a10 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
11a20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
11a30 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
11a40 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
11a50 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
11a60 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
11a70 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
11a80 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
11a90 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
11aa0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
11ab0 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
11ac0 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
11ad0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11ae0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
11af0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11b00 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
11b10 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
11b20 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
11b30 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
11b40 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
11b50 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
11b60 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11b70 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
11b80 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
11b90 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
11ba0 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
11bb0 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
11bc0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
11bd0 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
11be0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
11bf0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11c00 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
11c10 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
11c20 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
11c30 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
11c40 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
11c50 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
11c60 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
11c70 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
11c80 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
11c90 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
11ca0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
11cb0 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
11cc0 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
11cd0 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
11ce0 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
11cf0 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
11d00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
11d10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11d20 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
11d30 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
11d40 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
11d50 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
11d60 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
11d70 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
11d80 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
11d90 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
11da0 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
11db0 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
11dc0 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
11dd0 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
11de0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
11df0 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
11e00 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
11e10 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
11e20 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
11e30 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
11e40 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
11e50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
11e60 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
11e70 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
11e80 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
11e90 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11ea0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
11eb0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
11ec0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
11ed0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
11ee0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
11ef0 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
11f00 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
11f10 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
11f20 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
11f30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
11f40 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
11f50 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
11f60 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
11f70 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
11f80 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
11f90 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11fa0 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
11fb0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11fc0 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
11fd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
11fe0 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
11ff0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
12000 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69  NFIG_MALLOC opti
12010 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12020 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12030 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65   is .** a pointe
12040 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
12050 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12060 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
12070 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
12080 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
12090 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
120a0 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
120b0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
120c0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
120d0 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
120e0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
120f0 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
12100 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
12110 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
12120 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
12130 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
12140 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
12150 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12160 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
12170 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
12180 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12190 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
121a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
121b0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
121c0 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
121d0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
121e0 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
121f0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
12200 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70  FIG_GETMALLOC op
12210 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
12220 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
12230 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
12240 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
12250 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
12260 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
12270 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
12280 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12290 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
122a0 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
122b0 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
122c0 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
122d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
122e0 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
122f0 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
12300 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
12310 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
12320 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
12330 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
12340 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
12350 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
12360 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
12370 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
12380 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
12390 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
123a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
123b0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
123c0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
123d0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
123e0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
123f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
12400 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74  MSTATUS option t
12410 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
12420 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
12430 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64  ,.** interpreted
12440 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77   as a boolean, w
12450 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20  hich enables or 
12460 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c  disables the col
12470 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65  lection of.** me
12480 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12490 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68  statistics. ^(Wh
124a0 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  en memory alloca
124b0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
124c0 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68  are disabled, th
124d0 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  e .** following 
124e0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
124f0 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65  s become non-ope
12500 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
12510 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
12520 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
12530 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
12540 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
12550 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
12560 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
12570 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
12580 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  4()].**   <li> [
12590 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29  sqlite3_status()
125a0 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a  ].**   </ul>)^.*
125b0 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  * ^Memory alloca
125c0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
125d0 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
125e0 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51  efault unless SQ
125f0 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
12600 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
12610 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54  _DEFAULT_MEMSTAT
12620 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63  US]=0 in which c
12630 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ase memory.** al
12640 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
12650 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
12660 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20   by default..** 
12670 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12680 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
12690 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TCH]] <dt>SQLITE
126a0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c  _CONFIG_SCRATCH<
126b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
126c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
126d0 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 73  SCRATCH option s
126e0 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
126f0 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a  c memory buffer.
12700 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  ** that SQLite c
12710 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61 74  an use for scrat
12720 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68  ch memory.  ^(Th
12730 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
12740 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51  guments.** to SQ
12750 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
12760 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  TCH:  A pointer 
12770 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
12780 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  gned memory buff
12790 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  er from which th
127a0 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  e scratch alloca
127b0 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a  tions will be.**
127c0 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65   drawn, the size
127d0 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68   of each scratch
127e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29   allocation (sz)
127f0 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78  ,.** and the max
12800 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73  imum number of s
12810 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
12820 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65  ns (N).)^.** The
12830 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
12840 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65  must be a pointe
12850 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61  r to an 8-byte a
12860 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a  ligned buffer.**
12870 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
12880 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
12890 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
128a0 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20  ll not use more 
128b0 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68  than one scratch
128c0 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72   buffers per thr
128d0 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ead..** ^SQLite 
128e0 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65  will never reque
128f0 73 74 20 61 20 73 63 72 61 74 63 68 20 62 75 66  st a scratch buf
12900 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65  fer that is more
12910 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73   than 6.** times
12920 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
12930 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  ge size..** ^If 
12940 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65  SQLite needs nee
12950 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  ds additional.**
12960 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
12970 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
12980 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
12990 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
129a0 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b  tion, then .** [
129b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
129c0 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74  ] will be used t
129d0 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d  o obtain the mem
129e0 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a  ory needed.<p>.*
129f0 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c  * ^When the appl
12a00 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73  ication provides
12a10 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73   any amount of s
12a20 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73  cratch memory us
12a30 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  ing.** SQLITE_CO
12a40 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51  NFIG_SCRATCH, SQ
12a50 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65  Lite avoids unne
12a60 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a  cessary large.**
12a70 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
12a80 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e  |heap allocation
12a90 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20  s]..** This can 
12aa0 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f  help [Robson pro
12ab0 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72  of|prevent memor
12ac0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
12ad0 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65  lures] due to he
12ae0 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74  ap.** fragmentat
12af0 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72  ion in low-memor
12b00 79 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  y embedded syste
12b10 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ms..** </dd>.**.
12b20 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12b30 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c  IG_PAGECACHE]] <
12b40 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12b50 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a  _PAGECACHE</dt>.
12b60 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
12b70 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
12b80 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63  ACHE option spec
12b90 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
12ba0 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20  emory buffer.** 
12bb0 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
12bc0 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61  use for the data
12bd0 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20  base page cache 
12be0 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74  with the default
12bf0 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
12c00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
12c10 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75  .** This configu
12c20 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f  ration should no
12c30 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20  t be used if an 
12c40 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
12c50 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65  ne page.** cache
12c60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
12c70 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20  is loaded using 
12c80 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
12c90 49 47 5f 50 43 41 43 48 45 32 5d 0a 2a 2a 20 63  IG_PCACHE2].** c
12ca0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12cb0 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61  ion..** ^There a
12cc0 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
12cd0 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  ts to SQLITE_CON
12ce0 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41  FIG_PAGECACHE: A
12cf0 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79   pointer to 8-by
12d00 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65  te aligned.** me
12d10 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f  mory, the size o
12d20 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66  f each page buff
12d30 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65  er (sz), and the
12d40 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73   number of pages
12d50 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20   (N)..** The sz 
12d60 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
12d70 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  be the size of t
12d80 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62  he largest datab
12d90 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70  ase page.** (a p
12da0 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77  ower of two betw
12db0 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36  een 512 and 3276
12dc0 38 29 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74  8) plus some ext
12dd0 72 61 20 62 79 74 65 73 20 66 6f 72 20 65 61 63  ra bytes for eac
12de0 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
12df0 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  .  ^The number o
12e00 66 20 65 78 74 72 61 20 62 79 74 65 73 20 6e 65  f extra bytes ne
12e10 65 64 65 64 20 62 79 20 74 68 65 20 70 61 67 65  eded by the page
12e20 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62   header.** can b
12e30 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
12e40 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
12e50 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
12e60 53 5a 5d 20 6f 70 74 69 6f 6e 20 0a 2a 2a 20 74  SZ] option .** t
12e70 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
12e80 67 28 29 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20  g()]..** ^It is 
12e90 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20  harmless, apart 
12ea0 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20  from the wasted 
12eb0 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74  memory,.** for t
12ec0 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20  he sz parameter 
12ed0 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  to be larger tha
12ee0 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68  n necessary.  Th
12ef0 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d  e first.** argum
12f00 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74  ent should point
12f10 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
12f20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66  aligned block of
12f30 20 6d 65 6d 6f 72 79 20 74 68 61 74 0a 2a 2a 20   memory that.** 
12f40 69 73 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  is at least sz*N
12f50 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
12f60 2c 20 6f 74 68 65 72 77 69 73 65 20 73 75 62 73  , otherwise subs
12f70 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
12f80 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
12f90 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
12fa0 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20   use the memory 
12fb0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
12fc0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
12fd0 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a  o satisfy its.**
12fe0 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f   memory needs fo
12ff0 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61  r the first N pa
13000 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73  ges that it adds
13010 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20   to cache.  ^If 
13020 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61  additional.** pa
13030 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
13040 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64  is needed beyond
13050 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
13060 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e  d by this option
13070 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
13080 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65   goes to [sqlite
13090 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20  3_malloc()] for 
130a0 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73  the additional s
130b0 74 6f 72 61 67 65 20 73 70 61 63 65 2e 3c 2f 64  torage space.</d
130c0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
130d0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20  E_CONFIG_HEAP]] 
130e0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
130f0 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
13100 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
13110 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69  CONFIG_HEAP opti
13120 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
13130 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
13140 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c  fer .** that SQL
13150 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72  ite will use for
13160 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
13170 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  mic memory alloc
13180 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62  ation needs.** b
13190 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76  eyond those prov
131a0 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c  ided for by [SQL
131b0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
131c0 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  CH] and [SQLITE_
131d0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
131e0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54  ]..** ^The SQLIT
131f0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70  E_CONFIG_HEAP op
13200 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
13210 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65  ilable if SQLite
13220 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20   is compiled.** 
13230 77 69 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c  with either [SQL
13240 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
13250 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45  S3] or [SQLITE_E
13260 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61  NABLE_MEMSYS5] a
13270 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53  nd returns.** [S
13280 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
13290 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73  invoked otherwis
132a0 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65  e..** ^There are
132b0 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
132c0 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
132d0 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d  G_HEAP:.** An 8-
132e0 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69  byte aligned poi
132f0 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f  nter to the memo
13300 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  ry,.** the numbe
13310 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
13320 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c  e memory buffer,
13330 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d   and the minimum
13340 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
13350 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72  ..** ^If the fir
13360 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
13370 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
13380 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51  is NULL, then SQ
13390 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20  Lite reverts.** 
133a0 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66  to using its def
133b0 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
133c0 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65  cator (the syste
133d0 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65  m malloc() imple
133e0 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75  mentation),.** u
133f0 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72  ndoing any prior
13400 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
13410 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
13420 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a  LLOC].  ^If the.
13430 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  ** memory pointe
13440 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  r is not NULL th
13450 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
13460 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
13470 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
13480 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
13490 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
134a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
134b0 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ds..** The first
134c0 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
134d0 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75  mory pointer) mu
134e0 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
134f0 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f   an 8-byte.** bo
13500 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
13510 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
13520 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
13530 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
13540 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
13550 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70  tion size is cap
13560 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65  ped at 2**12. Re
13570 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a  asonable values.
13580 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d  ** for the minim
13590 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
135a0 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f  ze are 2**5 thro
135b0 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a  ugh 2**8.</dd>.*
135c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
135d0 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74  NFIG_MUTEX]] <dt
135e0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
135f0 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
13600 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
13610 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69  ONFIG_MUTEX opti
13620 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
13630 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
13640 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   is a.** pointer
13650 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
13660 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
13670 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
13680 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
13690 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
136a0 69 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20  ies alternative 
136b0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20  low-level mutex 
136c0 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
136d0 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20  sed in place.** 
136e0 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  the mutex routin
136f0 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
13700 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65  Lite.)^  ^SQLite
13710 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
13720 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20   the.** content 
13730 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
13740 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
13750 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20  tructure before 
13760 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  the call to.** [
13770 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13780 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53  ] returns. ^If S
13790 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
137a0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
137b0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
137c0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
137d0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
137e0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
137f0 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
13800 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
13810 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
13820 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
13830 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
13840 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
13850 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
13860 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
13870 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
13880 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
13890 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
138a0 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
138b0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
138c0 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  _GETMUTEX]] <dt>
138d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
138e0 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  TMUTEX</dt>.** <
138f0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
13900 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
13910 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
13920 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
13930 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
13940 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
13950 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
13960 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
13970 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
13980 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
13990 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a  mutex_methods].*
139a0 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
139b0 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
139c0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
139d0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
139e0 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
139f0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
13a00 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
13a10 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f  fault mutex allo
13a20 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
13a30 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
13a40 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20  r used to track 
13a50 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20  mutex usage for 
13a60 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70  performance.** p
13a70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74  rofiling or test
13a80 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  ing, for example
13a90 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
13aa0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
13ab0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
13ac0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
13ad0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
13ae0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
13af0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
13b00 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
13b10 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
13b20 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
13b30 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
13b40 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
13b50 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
13b60 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
13b70 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f  NFIG_GETMUTEX co
13b80 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13b90 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
13ba0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
13bb0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
13bc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
13bd0 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c  KASIDE]] <dt>SQL
13be0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
13bf0 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
13c00 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
13c10 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
13c20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
13c30 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
13c40 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65  determine.** the
13c50 20 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66   default size of
13c60 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
13c70 79 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62  y on each [datab
13c80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
13c90 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
13ca0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
13cb0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
13cc0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
13cd0 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  lot and the seco
13ce0 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nd is the number
13cf0 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c   of.** slots all
13d00 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64  ocated to each d
13d10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13d20 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f  on.)^  ^(SQLITE_
13d30 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
13d40 0a 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e  .** sets the <i>
13d50 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b  default</i> look
13d60 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20  aside size. The 
13d70 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
13d80 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f  _LOOKASIDE].** o
13d90 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65  ption to [sqlite
13da0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63  3_db_config()] c
13db0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68  an be used to ch
13dc0 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
13dd0 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  de.** configurat
13de0 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
13df0 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e  l connections.)^
13e00 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
13e10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
13e20 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
13e30 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
13e40 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
13e50 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
13e60 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e  G_PCACHE2 option
13e70 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
13e80 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
13e90 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
13ea0 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70  to an [sqlite3_p
13eb0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
13ec0 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62  object.  This ob
13ed0 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ject specifies.*
13ee0 2a 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  * the interface 
13ef0 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65  to a custom page
13f00 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
13f10 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c  ation.)^.** ^SQL
13f20 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
13f30 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
13f40 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
13f50 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a  ] object.</dd>.*
13f60 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13f70 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d  NFIG_GETPCACHE2]
13f80 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13f90 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f  FIG_GETPCACHE2</
13fa0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
13fb0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13fc0 47 45 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f  GETPCACHE2 optio
13fd0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
13fe0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a   argument which.
13ff0 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
14000 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70  to an [sqlite3_p
14010 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
14020 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20  object.  SQLite 
14030 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 75  copies of the cu
14040 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61  rrent.** page ca
14050 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
14060 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a  on into that obj
14070 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ect.)^ </dd>.**.
14080 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14090 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c  IG_LOG]] <dt>SQL
140a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f  ITE_CONFIG_LOG</
140b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20  dt>.** <dd> The 
140c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
140d0 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  G option is used
140e0 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68   to configure th
140f0 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62  e SQLite.** glob
14100 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a  al [error log]..
14110 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f  ** (^The SQLITE_
14120 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
14130 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
14140 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72  ments: a pointer
14150 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   to a.** functio
14160 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69  n with a call si
14170 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28  gnature of void(
14180 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  *)(void*,int,con
14190 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61  st char*), .** a
141a0 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  nd a pointer to 
141b0 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75  void. ^If the fu
141c0 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
141d0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69  s not NULL, it i
141e0 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20  s.** invoked by 
141f0 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
14200 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20  to process each 
14210 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20  logging event.  
14220 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  ^If the.** funct
14230 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e  ion pointer is N
14240 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ULL, the [sqlite
14250 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61  3_log()] interfa
14260 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d  ce becomes a no-
14270 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64  op..** ^The void
14280 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
14290 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
142a0 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43  ment to SQLITE_C
142b0 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20  ONFIG_LOG is.** 
142c0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
142d0 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
142e0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70  meter to the app
142f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
14300 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
14310 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61  ion whenever tha
14320 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e  t function is in
14330 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63  voked.  ^The sec
14340 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
14350 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66  .** the logger f
14360 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70  unction is a cop
14370 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70  y of the first p
14380 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
14390 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
143a0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
143b0 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74   call and is int
143c0 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72  ended to be a [r
143d0 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61  esult code] or a
143e0 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  n.** [extended r
143f0 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54  esult code].  ^T
14400 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
14410 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
14420 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f   logger is.** lo
14430 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20  g message after 
14440 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b  formatting via [
14450 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
14460 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ()]..** The SQLi
14470 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72  te logging inter
14480 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e  face is not reen
14490 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65  trant; the logge
144a0 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75  r function.** su
144b0 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70  pplied by the ap
144c0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
144d0 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51  ot invoke any SQ
144e0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
144f0 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68  ** In a multi-th
14500 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
14510 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  on, the applicat
14520 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
14530 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  er.** function m
14540 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
14550 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
14560 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
14570 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  RI]] <dt>SQLITE_
14580 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64  CONFIG_URI.** <d
14590 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  d>^(The SQLITE_C
145a0 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e  ONFIG_URI option
145b0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
145c0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
145d0 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d   int..** If non-
145e0 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68  zero, then URI h
145f0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
14600 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20  lly enabled. If 
14610 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
14620 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55   zero,.** then U
14630 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
14640 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
14650 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64  .)^ ^If URI hand
14660 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
14670 20 65 6e 61 62 6c 65 64 2c 0a 2a 2a 20 61 6c 6c   enabled,.** all
14680 20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65   filenames passe
14690 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d to [sqlite3_op
146a0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
146b0 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  open_v2()], [sql
146c0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f  ite3_open16()] o
146d0 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61  r.** specified a
146e0 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43  s part of [ATTAC
146f0 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20  H] commands are 
14700 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
14710 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a  RIs, regardless.
14720 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ** of whether or
14730 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45   not the [SQLITE
14740 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
14750 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  is set when the 
14760 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
14770 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
14780 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62  . ^If it is glob
14790 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66  ally disabled, f
147a0 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  ilenames are.** 
147b0 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64  only interpreted
147c0 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20   as URIs if the 
147d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
147e0 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
147f0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
14800 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
14810 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61  pened. ^(By defa
14820 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e  ult, URI handlin
14830 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
14840 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64   disabled. The d
14850 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79  efault value may
14860 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63   be changed by c
14870 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68  ompiling with th
14880 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45  e.** [SQLITE_USE
14890 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66  _URI] symbol def
148a0 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ined.)^.**.** [[
148b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
148c0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
148d0 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  N]] <dt>SQLITE_C
148e0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
148f0 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64  NDEX_SCAN.** <dd
14900 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
14910 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
14920 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74  EX_SCAN option t
14930 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e  akes a single in
14940 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  teger.** argumen
14950 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72  t which is inter
14960 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
14970 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ean in order to 
14980 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
14990 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  e.** the use of 
149a0 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
149b0 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
149c0 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65  scans in the que
149d0 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a  ry optimizer..**
149e0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
149f0 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69  tting is determi
14a00 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53  ned.** by the [S
14a10 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45  QLITE_ALLOW_COVE
14a20 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
14a30 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
14a40 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22  tion, or is "on"
14a50 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70  .** if that comp
14a60 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
14a70 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54  is omitted..** T
14a80 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69  he ability to di
14a90 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66  sable the use of
14aa0 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
14ab0 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
14ac0 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63   scans.** is bec
14ad0 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72  ause some incorr
14ae0 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61  ectly coded lega
14af0 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  cy applications 
14b00 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f  might malfunctio
14b10 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70  n.** when the op
14b20 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e  timization is en
14b30 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e  abled.  Providin
14b40 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f  g the ability to
14b50 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20  .** disable the 
14b60 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c  optimization all
14b70 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62  ows the older, b
14b80 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  uggy application
14b90 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   code to work.**
14ba0 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20   without change 
14bb0 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20  even with newer 
14bc0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
14bd0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  te..**.** [[SQLI
14be0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
14bf0 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ]] [[SQLITE_CONF
14c00 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a  IG_GETPCACHE]].*
14c10 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
14c20 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53  FIG_PCACHE and S
14c30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14c40 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54  PCACHE.** <dd> T
14c50 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65  hese options are
14c60 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68   obsolete and sh
14c70 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
14c80 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a   by new code..**
14c90 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e   They are retain
14ca0 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
14cb0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62   compatibility b
14cc0 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70  ut are now no-op
14cd0 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
14ce0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14cf0 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64  G_SQLLOG]].** <d
14d00 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14d10 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68  SQLLOG.** <dd>Th
14d20 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  is option is onl
14d30 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73  y available if s
14d40 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  qlite is compile
14d50 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
14d60 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c  QLITE_ENABLE_SQL
14d70 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73  LOG] pre-process
14d80 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64  or macro defined
14d90 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  . The first argu
14da0 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62  ment should.** b
14db0 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
14dc0 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
14dd0 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  e void(*)(void*,
14de0 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63  sqlite3*,const c
14df0 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54  har*, int)..** T
14e00 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64  he second should
14e10 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69   be of type (voi
14e20 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63  d*). The callbac
14e30 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  k is invoked by 
14e40 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69  the library.** i
14e50 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65  n three separate
14e60 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
14e70 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
14e80 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
14e90 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  s the.** fourth 
14ea0 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68  parameter. If th
14eb0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
14ec0 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68  er is 0, then th
14ed0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
14ee0 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20  ction.** passed 
14ef0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
14f00 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20  gument has just 
14f10 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65  been opened. The
14f20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
14f30 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62  ** points to a b
14f40 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67  uffer containing
14f50 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
14f60 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
14f70 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66  ile. If the.** f
14f80 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
14f90 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53  is 1, then the S
14fa0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
14fb0 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  t the third para
14fc0 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20  meter.** points 
14fd0 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  to has just been
14fe0 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69   executed. Or, i
14ff0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
15000 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65  ameter is 2, the
15010 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74  n.** the connect
15020 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64  ion being passed
15030 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
15040 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e  arameter is bein
15050 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a  g closed. The.**
15060 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
15070 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20   is passed NULL 
15080 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41  In this case.  A
15090 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69  n example of usi
150a0 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69  ng this.** confi
150b0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
150c0 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74  can be seen in t
150d0 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e  he "test_sqllog.
150e0 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69  c" source file i
150f0 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63  n.** the canonic
15100 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  al SQLite source
15110 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   tree.</dd>.**.*
15120 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15130 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  G_MMAP_SIZE]].**
15140 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15150 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20  IG_MMAP_SIZE.** 
15160 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46  <dd>^SQLITE_CONF
15170 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b  IG_MMAP_SIZE tak
15180 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e  es two 64-bit in
15190 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69  teger (sqlite3_i
151a0 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20  nt64) values.** 
151b0 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66  that are the def
151c0 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c  ault mmap size l
151d0 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c  imit (the defaul
151e0 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a  t setting for.**
151f0 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
15200 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78  ze]) and the max
15210 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61  imum allowed mma
15220 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a  p size limit..**
15230 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
15240 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65  tting can be ove
15250 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20  rridden by each 
15260 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15270 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74  ion using.** eit
15280 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20  her the [PRAGMA 
15290 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61  mmap_size] comma
152a0 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20  nd, or by using 
152b0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
152c0 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
152d0 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e  file control.  ^
152e0 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c  (The maximum all
152f0 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a  owed mmap size.*
15300 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74  * will be silent
15310 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20  ly truncated if 
15320 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61  necessary so tha
15330 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78  t it does not ex
15340 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ceed the.** comp
15350 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d  ile-time maximum
15360 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62   mmap size set b
15370 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
15380 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  _MAX_MMAP_SIZE] 
15390 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
153a0 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69  ion.)^.** ^If ei
153b0 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f  ther argument to
153c0 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
153d0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
153e0 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  hat argument is.
153f0 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74  ** changed to it
15400 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64  s compile-time d
15410 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  efault..**.** [[
15420 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
15430 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a  N32_HEAPSIZE]].*
15440 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
15450 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
15460 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  ZE.** <dd>^The S
15470 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
15480 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69  32_HEAPSIZE opti
15490 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
154a0 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
154b0 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f  s.** compiled fo
154c0 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74  r Windows with t
154d0 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32  he [SQLITE_WIN32
154e0 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f  _MALLOC] pre-pro
154f0 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66  cessor macro def
15500 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c 49 54 45  ined..** ^SQLITE
15510 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
15520 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33  APSIZE takes a 3
15530 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  2-bit unsigned i
15540 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20  nteger value.** 
15550 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
15560 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
15570 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68  of the created h
15580 65 61 70 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  eap..** </dl>.**
15590 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
155a0 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
155b0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
155c0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
155d0 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  DRSZ.** <dd>^The
155e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
155f0 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69  CACHE_HDRSZ opti
15600 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
15610 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
15620 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
15630 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
15640 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20  and writes into 
15650 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68 65  that integer the
15660 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61   number of extra
15670 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70 61  .** bytes per pa
15680 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 20  ge required for 
15690 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51  each page in [SQ
156a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
156b0 43 41 43 48 45 5d 2e 20 54 68 65 20 61 6d 6f 75  CACHE]. The amou
156c0 6e 74 20 6f 66 0a 2a 2a 20 65 78 74 72 61 20 73  nt of.** extra s
156d0 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63 61  pace required ca
156e0 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69  n change dependi
156f0 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ng on the compil
15700 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c  er,.** target pl
15710 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69  atform, and SQLi
15720 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 3c  te version..** <
15730 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
15740 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
15750 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
15760 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
15770 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
15780 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
15790 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
157a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
157b0 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
157c0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
157d0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
157e0 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
157f0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
15800 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
15810 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15820 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
15830 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
15840 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
15850 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15860 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
15870 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
15880 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
15890 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
158a0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
158b0 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
158c0 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
158d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
158e0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
158f0 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
15900 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
15910 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
15920 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15930 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
15940 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
15950 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15960 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
15970 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
15980 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
15990 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
159a0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
159b0 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
159c0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
159d0 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
159e0 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
159f0 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
15a00 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
15a10 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
15a20 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15a30 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
15a40 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
15a50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15a60 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
15a70 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    14  /* no-op *
15a80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15a90 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
15aa0 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f  E    15  /* no-o
15ab0 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
15ac0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20  ITE_CONFIG_LOG  
15ad0 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78          16  /* x
15ae0 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  Func, void* */.#
15af0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15b00 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20  NFIG_URI        
15b10 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a    17  /* int */.
15b20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15b30 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20  ONFIG_PCACHE2   
15b40 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65     18  /* sqlite
15b50 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
15b60 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
15b70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15b80 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20  CACHE2   19  /* 
15b90 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
15ba0 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66  ethods2* */.#def
15bb0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15bc0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
15bd0 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74  _SCAN 20  /* int
15be0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15bf0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
15c00 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53         21  /* xS
15c10 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a  qllog, void* */.
15c20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15c30 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20  ONFIG_MMAP_SIZE 
15c40 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65     22  /* sqlite
15c50 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33  3_int64, sqlite3
15c60 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e  _int64 */.#defin
15c70 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15c80 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20  WIN32_HEAPSIZE  
15c90 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e      23  /* int n
15ca0 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Byte */.#define 
15cb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15cc0 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20 20  ACHE_HDRSZ      
15cd0 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73    24  /* int *ps
15ce0 7a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  z */../*.** CAPI
15cf0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
15d00 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67  onnection Config
15d10 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
15d20 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
15d30 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
15d40 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
15d50 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
15d60 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
15d70 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
15d80 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
15d90 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
15da0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
15db0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
15dc0 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
15dd0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
15de0 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
15df0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
15e00 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
15e10 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
15e20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
15e30 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
15e40 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
15e50 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
15e60 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
15e70 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
15e80 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
15e90 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
15ea0 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
15eb0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
15ec0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
15ed0 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
15ee0 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
15ef0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
15f00 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
15f10 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
15f20 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
15f30 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
15f40 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
15f50 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
15f60 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
15f70 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
15f80 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
15f90 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
15fa0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
15fb0 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
15fc0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
15fd0 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
15fe0 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
15ff0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
16000 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
16010 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
16020 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
16030 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
16040 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
16050 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
16060 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  a memory buffer 
16070 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61  to use for looka
16080 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  side memory..** 
16090 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
160a0 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51  ent after the SQ
160b0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
160c0 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20  OKASIDE verb.** 
160d0 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
160e0 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
160f0 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
16100 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
16110 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
16120 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
16130 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63  loc()]. ^The sec
16140 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
16150 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
16160 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
16170 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65  ffer slot.  ^The
16180 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
16190 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
161a0 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
161b0 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
161c0 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
161d0 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
161e0 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
161f0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
16200 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
16210 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
16220 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
16230 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20   buffer.** must 
16240 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
16250 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
16260 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  .  ^If the secon
16270 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
16280 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
16290 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f  _LOOKASIDE is no
162a0 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  t a multiple of 
162b0 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61  8, it is interna
162c0 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64  lly.** rounded d
162d0 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
162e0 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65  smaller multiple
162f0 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f   of 8.  ^(The lo
16300 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a  okaside memory.*
16310 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
16320 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
16330 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e  onnection can on
16340 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68  ly be changed wh
16350 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65  en that.** conne
16360 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72  ction is not cur
16370 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f  rently using loo
16380 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f  kaside memory, o
16390 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  r in other words
163a0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75  .** when the "cu
163b0 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74  rrent value" ret
163c0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
163d0 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28  ite3_db_status](
163e0 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  D,[SQLITE_CONFIG
163f0 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29  _LOOKASIDE],...)
16400 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79   is zero..** Any
16410 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e   attempt to chan
16420 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
16430 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72   memory configur
16440 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61  ation when looka
16450 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69  side.** memory i
16460 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20  s in use leaves 
16470 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
16480 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20  n unchanged and 
16490 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
164a0 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64  ITE_BUSY].)^</dd
164b0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
164c0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
164d0 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20  LE_FKEY</dt>.** 
164e0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
164f0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
16500 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
16510 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  he enforcement o
16520 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  f.** [foreign ke
16530 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20  y constraints]. 
16540 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
16550 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
16560 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
16570 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
16580 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
16590 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
165a0 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
165b0 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ent,.** positive
165c0 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e   to enable FK en
165d0 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67  forcement or neg
165e0 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46  ative to leave F
165f0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a  K enforcement.**
16600 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
16610 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
16620 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
16630 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
16640 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
16650 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
16660 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
16670 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
16680 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20  is off or on.** 
16690 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
166a0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
166b0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
166c0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
166d0 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
166e0 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63  se the FK enforc
166f0 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73  ement setting is
16700 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
16710 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
16720 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
16730 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
16740 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
16750 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
16760 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
16770 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54  r disable [CREAT
16780 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
16790 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  gers]..** There 
167a0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
167b0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
167c0 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
167d0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
167e0 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
167f0 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72   0 to disable tr
16800 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74  iggers,.** posit
16810 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72  ive to enable tr
16820 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69  iggers or negati
16830 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
16840 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
16850 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
16860 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
16870 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
16880 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
16890 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
168a0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
168b0 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65  e whether trigge
168c0 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  rs are disabled 
168d0 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
168e0 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
168f0 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
16900 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
16910 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
16920 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
16930 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74   the trigger set
16940 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
16950 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
16960 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
16970 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
16980 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
16990 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a  E       1001  /*
169a0 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
169b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
169c0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
169d0 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20  _FKEY     1002  
169e0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
169f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
16a00 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
16a10 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20  IGGER  1003  /* 
16a20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a  int int* */.../*
16a30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
16a40 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
16a50 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
16a60 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Codes.**.** ^The
16a70 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
16a80 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
16a90 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
16aa0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
16ab0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
16ac0 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
16ad0 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e  ure of SQLite. ^
16ae0 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
16af0 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65  ult.** codes are
16b00 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
16b10 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69  ault for histori
16b20 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
16b30 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  y..*/.int sqlite
16b40 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
16b50 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
16b60 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
16b70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
16b80 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
16b90 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74  .**.** ^Each ent
16ba0 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74  ry in most SQLit
16bb0 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74  e tables (except
16bc0 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f   for [WITHOUT RO
16bd0 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20  WID] tables).** 
16be0 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
16bf0 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
16c00 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
16c10 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
16c20 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77  owid"]. ^The row
16c30 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
16c40 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
16c50 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
16c60 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
16c70 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
16c80 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
16c90 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
16ca0 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
16cb0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
16cc0 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a  d columns. ^If.*
16cd0 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
16ce0 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
16cf0 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
16d00 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
16d10 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
16d20 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
16d30 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
16d40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61   ^The sqlite3_la
16d50 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
16d60 44 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  D) interface ret
16d70 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  urns the [rowid]
16d80 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74   of the .** most
16d90 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66   recent successf
16da0 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
16db0 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f   a rowid table o
16dc0 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  r [virtual table
16dd0 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65  ].** on database
16de0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a   connection D..*
16df0 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20  * ^Inserts into 
16e00 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20  [WITHOUT ROWID] 
16e10 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72  tables are not r
16e20 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  ecorded..** ^If 
16e30 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  no successful [I
16e40 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77  NSERT]s into row
16e50 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76  id tables.** hav
16e60 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20  e ever occurred 
16e70 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
16e80 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a  connection D, .*
16e90 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c  * then sqlite3_l
16ea0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
16eb0 28 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  (D) returns zero
16ec0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20  ..**.** ^(If an 
16ed0 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20  [INSERT] occurs 
16ee0 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
16ef0 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69   or within a [vi
16f00 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20  rtual table].** 
16f10 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69  method, then thi
16f20 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72  s routine will r
16f30 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64  eturn the [rowid
16f40 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65  ] of the inserte
16f50 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67  d.** row as long
16f60 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
16f70 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
16f80 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69   method is runni
16f90 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20  ng..** But once 
16fa0 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
16fb0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74  irtual table met
16fc0 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61  hod ends, the va
16fd0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a  lue returned .**
16fe0 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
16ff0 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74   reverts to what
17000 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74   it was before t
17010 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
17020 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d  rtual.** table m
17030 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a  ethod began.)^.*
17040 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
17050 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
17060 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
17070 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
17080 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
17090 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
170a0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
170b0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
170c0 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
170d0 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
170e0 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
170f0 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
17100 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
17110 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
17120 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
17130 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
17140 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
17150 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
17160 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
17170 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
17180 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
17190 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
171a0 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
171b0 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
171c0 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
171d0 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
171e0 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
171f0 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
17200 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
17210 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
17220 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
17230 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
17240 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
17250 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
17260 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
17270 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
17280 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
17290 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
172a0 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
172b0 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
172c0 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
172d0 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
172e0 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
172f0 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
17300 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
17310 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
17320 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
17330 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
17340 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
17350 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
17360 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
17370 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
17380 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
17390 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
173a0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
173b0 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
173c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
173d0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
173e0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
173f0 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
17400 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
17410 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
17420 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
17430 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
17440 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
17450 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
17460 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
17470 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
17480 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
17490 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
174a0 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
174b0 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74  rowid]..*/.sqlit
174c0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
174d0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
174e0 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
174f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
17500 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
17510 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
17520 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
17530 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
17540 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
17550 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72   modified, inser
17560 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65  ted or.** delete
17570 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
17580 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
17590 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
175a0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
175b0 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61  tement on the da
175c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
175d0 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  n specified by t
175e0 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
175f0 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67  r..** ^Executing
17600 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
17610 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
17620 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79   does not modify
17630 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
17640 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66  turned by this f
17650 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  unction..**.** ^
17660 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64  Only changes mad
17670 65 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68  e directly by th
17680 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  e INSERT, UPDATE
17690 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
176a0 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73  ment are.** cons
176b0 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61  idered - auxilia
176c0 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
176d0 64 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49  d by [CREATE TRI
176e0 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
176f0 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  , .** [foreign k
17700 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b  ey actions] or [
17710 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
17720 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
17730 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a  re not counted..
17740 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74  ** .** Changes t
17750 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
17760 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79  e intercepted by
17770 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46   .** [INSTEAD OF
17780 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45   trigger | INSTE
17790 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20  AD OF triggers] 
177a0 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
177b0 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20   ^The value .** 
177c0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
177d0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d  te3_changes() im
177e0 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20  mediately after 
177f0 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
17800 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20  E or .** DELETE 
17810 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e  statement run on
17820 20 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79   a view is alway
17830 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61  s zero. Only cha
17840 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61  nges made to rea
17850 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65  l .** tables are
17860 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
17870 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20  Things are more 
17880 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74  complicated if t
17890 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
178a0 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
178b0 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69  .** executed whi
178c0 6c 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  le a trigger pro
178d0 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e  gram is running.
178e0 20 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e   This may happen
178f0 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72   if the.** progr
17900 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61  am uses the [cha
17910 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
17920 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65  ion], or if some
17930 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a   other callback.
17940 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f  ** function invo
17950 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  kes sqlite3_chan
17960 67 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ges() directly. 
17970 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20  Essentially:.** 
17980 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
17990 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65  i> ^(Before ente
179a0 72 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70  ring a trigger p
179b0 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65  rogram the value
179c0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
179d0 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63         sqlite3_c
179e0 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
179f0 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65  n is saved. Afte
17a00 72 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72  r the trigger pr
17a10 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20  ogram .**       
17a20 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74   has finished, t
17a30 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75  he original valu
17a40 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e  e is restored.)^
17a50 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  .** .**   <li> ^
17a60 28 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65  (Within a trigge
17a70 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49  r program each I
17a80 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e  NSERT, UPDATE an
17a90 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20  d DELETE .**    
17aa0 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65      statement se
17ab0 74 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ts the value ret
17ac0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
17ad0 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20  _changes() .**  
17ae0 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c        upon compl
17af0 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e  etion as normal.
17b00 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73   Of course, this
17b10 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20   value will not 
17b20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20  include .**     
17b30 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70     any changes p
17b40 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d  erformed by sub-
17b50 74 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65  triggers, as the
17b60 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
17b70 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61  () .**        va
17b80 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65  lue will be save
17b90 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61  d and restored a
17ba0 66 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72  fter each sub-tr
17bb0 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e  igger has run.)^
17bc0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a  .** </ul>.** .**
17bd0 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61   ^This means tha
17be0 74 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73  t if the changes
17bf0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  () SQL function 
17c00 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20  (or similar) is 
17c10 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66  used.** by the f
17c20 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44  irst INSERT, UPD
17c30 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
17c40 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
17c50 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a   trigger, it .**
17c60 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
17c70 75 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74  ue as set when t
17c80 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65  he calling state
17c90 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75  ment began execu
17ca0 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20  ting..** ^If it 
17cb0 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73  is used by the s
17cc0 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75  econd or subsequ
17cd0 65 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65  ent such stateme
17ce0 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  nt within a trig
17cf0 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c  ger .** program,
17d00 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
17d10 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65  ned reflects the
17d20 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
17d30 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20  modified by the 
17d40 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53  .** previous INS
17d50 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
17d60 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
17d70 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
17d80 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53  trigger..**.** S
17d90 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
17da0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
17db0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
17dc0 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
17dd0 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
17de0 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73  and the [changes
17df0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
17e00 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
17e10 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
17e20 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
17e30 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
17e40 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
17e50 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
17e60 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
17e70 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
17e80 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  e returned.** is
17e90 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
17ea0 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
17eb0 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
17ec0 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  3_changes(sqlite
17ed0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
17ee0 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62  3REF: Total Numb
17ef0 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
17f00 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
17f10 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
17f20 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
17f30 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74  r of rows insert
17f40 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a  ed, modified or.
17f50 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c  ** deleted by al
17f60 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44  l [INSERT], [UPD
17f70 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
17f80 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70   statements comp
17f90 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74  leted.** since t
17fa0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
17fb0 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65  ection was opene
17fc0 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f  d, including tho
17fd0 73 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a  se executed as.*
17fe0 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65  * part of trigge
17ff0 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65  r programs. ^Exe
18000 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72  cuting any other
18010 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61   type of SQL sta
18020 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e  tement.** does n
18030 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61  ot affect the va
18040 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
18050 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
18060 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20  anges()..** .** 
18070 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73  ^Changes made as
18080 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67   part of [foreig
18090 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61  n key actions] a
180a0 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  re included in t
180b0 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74  he.** count, but
180c0 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70   those made as p
180d0 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63  art of REPLACE c
180e0 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
180f0 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e  tion are.** not.
18100 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76   ^Changes to a v
18110 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74  iew that are int
18120 65 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54  ercepted by INST
18130 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20  EAD OF triggers 
18140 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  .** are not coun
18150 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20  ted..** .** See 
18160 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
18170 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  3_changes()] int
18180 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
18190 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
181a0 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
181b0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
181c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
181d0 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
181e0 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
181f0 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
18200 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
18210 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
18220 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
18230 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
18240 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
18250 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
18260 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
18270 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
18280 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
18290 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
182a0 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
182b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
182c0 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d  nterrupt A Long-
182d0 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a  Running Query.**
182e0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
182f0 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
18300 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
18310 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
18320 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
18330 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
18340 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
18350 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
18360 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
18370 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
18380 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
18390 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
183a0 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
183b0 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
183c0 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
183d0 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
183e0 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
183f0 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
18400 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
18410 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
18420 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
18430 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
18440 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
18450 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
18460 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
18470 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
18480 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
18490 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
184a0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
184b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
184c0 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
184d0 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
184e0 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
184f0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
18500 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
18510 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
18520 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
18530 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
18540 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
18550 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
18560 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
18570 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
18580 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
18590 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
185a0 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
185b0 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
185c0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
185d0 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
185e0 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
185f0 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
18600 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
18610 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
18620 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
18630 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
18640 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
18650 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
18660 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
18670 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
18680 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
18690 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
186a0 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
186b0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
186c0 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
186d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
186e0 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
186f0 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
18700 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
18710 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
18720 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
18730 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18740 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
18750 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
18760 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
18770 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
18780 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
18790 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
187a0 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
187b0 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
187c0 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
187d0 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
187e0 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
187f0 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
18800 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
18810 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
18820 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
18830 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
18840 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
18850 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
18860 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
18870 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
18880 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
18890 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
188a0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
188b0 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
188c0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
188d0 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
188e0 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
188f0 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
18900 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
18910 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
18920 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
18930 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
18940 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
18950 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
18960 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
18970 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ll returns..**.*
18980 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  * If the databas
18990 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
189a0 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ses while [sqlit
189b0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
189c0 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  ** is running th
189d0 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69  en bad things wi
189e0 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e  ll likely happen
189f0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
18a00 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
18a10 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
18a20 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
18a30 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
18a40 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
18a50 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e.**.** These ro
18a60 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
18a70 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64  l during command
18a80 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
18a90 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
18aa0 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
18ab0 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
18ac0 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65  to form a comple
18ad0 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
18ae0 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
18af0 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
18b00 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
18b10 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
18b20 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
18b30 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65  parsing.  ^These
18b40 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
18b50 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
18b60 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
18b70 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
18b80 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
18b90 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20  .  ^A statement 
18ba0 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
18bb0 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
18bc0 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
18bd0 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
18be0 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69  d is not a prefi
18bf0 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66  x of a.** well-f
18c00 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49  ormed CREATE TRI
18c10 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
18c20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61   ^Semicolons tha
18c30 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
18c40 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
18c50 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
18c60 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
18c70 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
18c80 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
18c90 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
18ca0 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
18cb0 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
18cc0 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
18cd0 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
18ce0 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
18cf0 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
18d00 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74  rminator.  ^Whit
18d10 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f  espace.** and co
18d20 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c  mments that foll
18d30 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d  ow the final sem
18d40 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72  icolon are ignor
18d50 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
18d60 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
18d70 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d   0 if the statem
18d80 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74  ent is incomplet
18d90 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d  e.  ^If a.** mem
18da0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
18db0 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54  ails, then SQLIT
18dc0 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72  E_NOMEM is retur
18dd0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
18de0 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
18df0 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
18e00 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
18e10 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
18e20 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
18e30 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
18e40 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
18e50 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69  e has not been i
18e60 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67  nitialized using
18e70 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
18e80 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a  lize()] prior .*
18e90 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71  * to invoking sq
18ea0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
18eb0 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  () then sqlite3_
18ec0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
18ed0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d  invoked.** autom
18ee0 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
18ef0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
18f00 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69  .  If that initi
18f10 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c  alization fails,
18f20 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
18f30 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
18f40 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
18f50 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d  6() will be non-
18f60 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65  zero.** regardle
18f70 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
18f80 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53   not the input S
18f90 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29  QL is complete.)
18fa0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ^.**.** The inpu
18fb0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
18fc0 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62  mplete()] must b
18fd0 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
18fe0 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
18ff0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ing..**.** The i
19000 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
19010 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d  _complete16()] m
19020 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
19030 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
19040 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
19050 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
19060 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
19070 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
19080 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71  ar *sql);.int sq
19090 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
190a0 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
190b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
190c0 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
190d0 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
190e0 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
190f0 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rors.**.** ^The 
19100 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
19110 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74  dler(D,X,P) rout
19120 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
19130 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a  ack function X.*
19140 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  * that might be 
19150 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67  invoked with arg
19160 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72  ument P whenever
19170 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69  .** an attempt i
19180 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73  s made to access
19190 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
191a0 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  e associated wit
191b0 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
191c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65  onnection] D whe
191d0 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  n another thread
191e0 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
191f0 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63  as the table loc
19200 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ked..** The sqli
19210 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
19220 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
19230 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
19240 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  t.** [sqlite3_bu
19250 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e  sy_timeout()] an
19260 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74  d [PRAGMA busy_t
19270 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  imeout]..**.** ^
19280 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
19290 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
192a0 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
192b0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
192c0 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
192d0 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
192e0 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
192f0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
19300 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
19310 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
19320 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
19330 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
19340 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
19350 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
19360 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
19370 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
19380 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
19390 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
193a0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
193b0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
193c0 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
193d0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
193e0 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
193f0 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
19400 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
19410 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
19420 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
19430 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
19440 6b 65 64 20 66 6f 72 20 74 68 65 20 73 61 6d 65  ked for the same
19450 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20   locking event. 
19460 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79   ^If the.** busy
19470 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
19480 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64  s 0, then no add
19490 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73  itional attempts
194a0 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20   are made to.** 
194b0 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
194c0 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ase and [SQLITE_
194d0 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65  BUSY] is returne
194e0 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c  d.** to the appl
194f0 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20  ication..** ^If 
19500 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
19510 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
19520 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
19530 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
19540 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
19550 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63 79  abase and the cy
19560 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a  cle repeats..**.
19570 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20  ** The presence 
19580 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  of a busy handle
19590 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61  r does not guara
195a0 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c  ntee that it wil
195b0 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  l be invoked.** 
195c0 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f  when there is lo
195d0 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e  ck contention. ^
195e0 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
195f0 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
19600 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ng the busy.** h
19610 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
19620 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63  ult in a deadloc
19630 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68  k, it will go ah
19640 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ead and return [
19650 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
19660 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
19670 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e  on instead of in
19680 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62  voking the .** b
19690 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
196a0 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
196b0 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
196c0 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
196d0 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
196e0 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
196f0 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
19700 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
19710 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
19720 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
19730 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
19740 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
19750 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
19760 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
19770 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
19780 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
19790 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
197a0 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
197b0 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
197c0 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
197d0 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
197e0 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
197f0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
19800 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
19810 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
19820 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
19830 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
19840 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
19850 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
19860 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
19870 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
19880 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
19890 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
198a0 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
198b0 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
198c0 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
198d0 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
198e0 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
198f0 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
19900 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
19910 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  proceed..**.** ^
19920 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
19930 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
19940 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  L..**.** ^(There
19950 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
19960 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
19970 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
19980 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
19990 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53   connection].  S
199a0 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
199b0 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
199c0 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73   any.** previous
199d0 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29  ly set handler.)
199e0 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61  ^  ^Note that ca
199f0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  lling [sqlite3_b
19a00 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a  usy_timeout()].*
19a10 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20  * or evaluating 
19a20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
19a30 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61  eout=N] will cha
19a40 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  nge the.** busy 
19a50 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73  handler and thus
19a60 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69   clear any previ
19a70 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20 68  ously set busy h
19a80 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  andler..**.** Th
19a90 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
19aa0 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20  should not take 
19ab0 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63  any actions whic
19ac0 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20  h modify the.** 
19ad0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19ae0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
19af0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
19b00 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  r.  In other wor
19b10 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20  ds,.** the busy 
19b20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72  handler is not r
19b30 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73  eentrant.  Any s
19b40 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72  uch actions.** r
19b50 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
19b60 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20  ed behavior..** 
19b70 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c  .** A busy handl
19b80 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  er must not clos
19b90 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
19ba0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20  onnection.** or 
19bb0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
19bc0 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65  ent] that invoke
19bd0 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
19be0 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
19bf0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
19c00 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
19c10 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69  (void*,int), voi
19c20 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
19c30 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
19c40 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e   Timeout.**.** ^
19c50 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
19c60 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
19c70 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
19c80 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
19c90 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
19ca0 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
19cb0 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
19cc0 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
19cd0 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a   ^The handler.**
19ce0 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
19cf0 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
19d00 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
19d10 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
19d20 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20  leeping.** have 
19d30 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41  accumulated.  ^A
19d40 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d  fter at least "m
19d50 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
19d60 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
19d70 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
19d80 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
19d90 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
19da0 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
19db0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
19dc0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74  **.** ^Calling t
19dd0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
19de0 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
19df0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
19e00 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
19e10 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
19e20 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ndlers..**.** ^(
19e30 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
19e40 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
19e50 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
19e60 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
19e70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19e80 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d  ] at any given m
19e90 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68  oment.  If anoth
19ea0 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a  er busy handler.
19eb0 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20  ** was defined  
19ec0 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  (using [sqlite3_
19ed0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29  busy_handler()])
19ee0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
19ef0 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  g.** this routin
19f00 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75  e, that other bu
19f10 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c  sy handler is cl
19f20 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  eared.)^.**.** S
19f30 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d  ee also:  [PRAGM
19f40 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a  A busy_timeout].
19f50 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
19f60 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
19f70 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
19f80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19f90 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
19fa0 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
19fb0 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54   Queries.**.** T
19fc0 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20  his is a legacy 
19fd0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69  interface that i
19fe0 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20  s preserved for 
19ff0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1a000 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20  ibility..** Use 
1a010 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
1a020 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65  e is not recomme
1a030 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69  nded..**.** Defi
1a040 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
1a050 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
1a060 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
1a070 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
1a080 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
1a090 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
1a0a0 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
1a0b0 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
1a0c0 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
1a0d0 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
1a0e0 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
1a0f0 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
1a100 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
1a110 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
1a120 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
1a130 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
1a140 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
1a150 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
1a160 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1a170 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
1a180 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
1a190 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
1a1a0 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
1a1b0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
1a1c0 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
1a1d0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1a1e0 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
1a1f0 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
1a200 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
1a210 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
1a220 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
1a230 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
1a240 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
1a250 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
1a260 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
1a270 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
1a280 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1a290 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
1a2a0 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
1a2b0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
1a2c0 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
1a2d0 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
1a2e0 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
1a2f0 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
1a300 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
1a310 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
1a320 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
1a330 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
1a340 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
1a350 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
1a360 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
1a370 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1a380 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
1a390 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
1a3a0 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
1a3b0 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
1a3c0 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
1a3d0 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
1a3e0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
1a3f0 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
1a400 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
1a410 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1a420 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1a430 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
1a440 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
1a450 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1a460 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  le()]..**.** ^(A
1a470 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
1a480 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1a490 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
1a4a0 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
1a4b0 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
1a4c0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1a4d0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
1a4e0 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
1a4f0 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
1a500 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1a510 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
1a520 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
1a530 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
1a540 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
1a550 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
1a560 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
1a570 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1a580 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
1a590 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
1a5a0 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
1a5b0 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
1a5c0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
1a5d0 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
1a5e0 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
1a5f0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
1a600 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
1a610 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
1a620 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
1a630 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
1a640 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
1a650 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1a660 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1a670 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
1a680 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1a690 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
1a6a0 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
1a6b0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
1a6c0 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
1a6d0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1a6e0 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
1a6f0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1a700 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
1a710 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1a720 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
1a730 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1a740 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
1a750 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
1a760 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
1a770 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
1a780 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1a790 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
1a7a0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1a7b0 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
1a7c0 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
1a7d0 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
1a7e0 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
1a7f0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
1a800 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1a810 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
1a820 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
1a830 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  er and returns a
1a840 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
1a850 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
1a860 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
1a870 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1a880 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c  * After the appl
1a890 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  ication has fini
1a8a0 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65  shed with the re
1a8b0 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65  sult from sqlite
1a8c0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a  3_get_table(),.*
1a8d0 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74  * it must pass t
1a8e0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1a8f0 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
1a900 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
1a910 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
1a920 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1a930 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
1a940 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
1a950 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
1a960 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1a970 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
1a980 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
1a990 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
1a9a0 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
1a9b0 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
1a9c0 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
1a9d0 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
1a9e0 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
1a9f0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
1aa00 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
1aa10 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
1aa20 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
1aa30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1aa40 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1aa50 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
1aa60 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
1aa70 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
1aa80 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1aa90 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
1aaa0 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
1aab0 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
1aac0 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
1aad0 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
1aae0 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
1aaf0 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
1ab00 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
1ab10 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
1ab20 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
1ab30 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
1ab40 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
1ab50 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
1ab60 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
1ab70 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
1ab80 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
1ab90 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
1aba0 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
1abb0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
1abc0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1abd0 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
1abe0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
1abf0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
1ac00 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
1ac10 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1ac20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
1ac30 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
1ac40 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1ac50 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
1ac60 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
1ac70 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
1ac80 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
1ac90 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
1aca0 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
1acb0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
1acc0 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
1acd0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
1ace0 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
1acf0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1ad00 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
1ad10 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
1ad20 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
1ad30 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
1ad40 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
1ad50 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
1ad60 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1ad70 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
1ad80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ad90 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
1ada0 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
1adb0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
1adc0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1add0 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
1ade0 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
1adf0 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
1ae00 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
1ae10 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1ae20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1ae30 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
1ae40 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
1ae50 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
1ae60 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
1ae70 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
1ae80 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
1ae90 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1aea0 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
1aeb0 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
1aec0 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
1aed0 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
1aee0 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
1aef0 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42  te3_free()].  ^B
1af00 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
1af10 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
1af20 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
1af30 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
1af40 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1af50 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
1af60 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
1af70 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
1af80 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
1af90 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
1afa0 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
1afb0 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
1afc0 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
1afd0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1afe0 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
1aff0 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
1b000 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
1b010 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
1b020 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
1b030 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
1b040 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
1b050 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
1b060 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
1b070 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
1b080 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
1b090 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
1b0a0 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20   snprintf().)^  
1b0b0 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69  This is an.** hi
1b0c0 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e  storical acciden
1b0d0 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65  t that cannot be
1b0e0 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62   fixed without b
1b0f0 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77  reaking.** backw
1b100 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1b110 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f  ty.  ^(Note also
1b120 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
1b130 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
1b140 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1b150 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
1b160 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
1b170 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
1b180 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
1b190 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
1b1a0 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74  fer.)^  We admit
1b1b0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
1b1c0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
1b1d0 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
1b1e0 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
1b1f0 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
1b200 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
1b210 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
1b220 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
1b230 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1b240 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
1b250 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
1b260 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  lity..**.** ^As 
1b270 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
1b280 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
1b290 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
1b2a0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1b2b0 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
1b2c0 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
1b2d0 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
1b2e0 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
1b2f0 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
1b300 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
1b310 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
1b320 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
1b330 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
1b340 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
1b350 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
1b360 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
1b370 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
1b380 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
1b390 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
1b3a0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ers..**.** ^The 
1b3b0 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
1b3c0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61  f() routine is a
1b3d0 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e   varargs version
1b3e0 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1b3f0 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  intf()..**.** Th
1b400 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c  ese routines all
1b410 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20   implement some 
1b420 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61  additional forma
1b430 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73  tting.** options
1b440 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c   that are useful
1b450 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e   for constructin
1b460 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  g SQL statements
1b470 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20  ..** All of the 
1b480 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66  usual printf() f
1b490 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1b4a0 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64  s apply.  In add
1b4b0 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20  ition, there.** 
1b4c0 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51  is are "%q", "%Q
1b4d0 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69  ", and "%z" opti
1b4e0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ons..**.** ^(The
1b4f0 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
1b500 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
1b510 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
1b520 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
1b530 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
1b540 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
1b550 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
1b560 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
1b570 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
1b580 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
1b590 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
1b5a0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1b5b0 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  )^  By doubling 
1b5c0 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
1b5d0 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
1b5e0 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
1b5f0 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
1b600 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
1b610 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
1b620 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
1b630 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
1b640 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
1b650 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
1b660 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
1b670 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1b680 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1b690 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
1b6a0 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
1b6b0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1b6c0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
1b6d0 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
1b6e0 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
1b6f0 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
1b700 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1b710 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1b720 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1b730 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1b740 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1b750 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
1b760 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
1b770 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
1b780 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
1b790 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
1b7a0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1b7b0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
1b7c0 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
1b7d0 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
1b7e0 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
1b7f0 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
1b800 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
1b810 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
1b820 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
1b830 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1b840 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1b850 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1b860 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
1b870 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
1b880 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1b890 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1b8a0 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
1b8b0 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
1b8c0 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
1b8d0 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
1b8e0 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
1b8f0 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
1b900 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1b910 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1b920 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1b930 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
1b940 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
1b950 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1b960 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
1b970 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
1b980 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
1b990 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
1b9a0 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
1b9b0 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
1b9c0 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
1b9d0 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
1b9e0 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
1b9f0 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
1ba00 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f  * ^(The %Q optio
1ba10 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
1ba20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
1ba30 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
1ba40 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
1ba50 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
1ba60 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
1ba70 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
1ba80 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
1ba90 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
1baa0 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
1bab0 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
1bac0 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
1bad0 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
1bae0 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
1baf0 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ).)^  So, for ex
1bb00 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
1bb10 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
1bb20 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1bb30 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1bb40 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1bb50 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1bb60 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
1bb70 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1bb80 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1bb90 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1bba0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1bbb0 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1bbc0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1bbd0 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
1bbe0 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
1bbf0 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
1bc00 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
1bc10 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
1bc20 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
1bc30 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
1bc40 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1bc50 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61  ^(The "%z" forma
1bc60 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72  tting option wor
1bc70 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74  ks like "%s" but
1bc80 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
1bc90 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
1bca0 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
1bcb0 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
1bcc0 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
1bcd0 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
1bce0 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
1bcf0 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
1bd00 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68   string.)^.*/.ch
1bd10 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
1bd20 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1bd30 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
1bd40 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
1bd50 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
1bd60 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
1bd70 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
1bd80 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1bd90 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  , ...);.char *sq
1bda0 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1bdb0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1bdc0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1bdd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1bde0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1bdf0 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
1be00 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
1be10 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
1be20 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
1be30 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
1be40 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
1be50 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
1be60 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
1be70 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
1be80 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
1be90 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
1bea0 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
1beb0 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
1bec0 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
1bed0 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
1bee0 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
1bef0 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
1bf00 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
1bf10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1bf20 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
1bf30 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
1bf40 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
1bf50 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
1bf60 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1bf70 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
1bf80 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
1bf90 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
1bfa0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1bfb0 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
1bfc0 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
1bfd0 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
1bfe0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1bff0 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
1c000 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
1c010 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1c020 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
1c030 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
1c040 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
1c050 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
1c060 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
1c070 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1c080 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77  c64(N) routine w
1c090 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a  orks just like.*
1c0a0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1c0b0 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  (N) except that 
1c0c0 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64  N is an unsigned
1c0d0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
1c0e0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
1c0f0 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e  signed 32-bit in
1c100 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  teger..**.** ^Ca
1c110 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  lling sqlite3_fr
1c120 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ee() with a poin
1c130 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72  ter previously r
1c140 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1c150 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1c160 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1c170 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61  c() releases tha
1c180 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74  t memory so.** t
1c190 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20  hat it might be 
1c1a0 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71  reused.  ^The sq
1c1b0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
1c1c0 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
1c1d0 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
1c1e0 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
1c1f0 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
1c200 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
1c210 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
1c220 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
1c230 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65  After being free
1c240 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f  d, memory.** sho
1c250 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72  uld neither be r
1c260 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e  ead nor written.
1c270 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70    Even reading p
1c280 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a  reviously freed.
1c290 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20  ** memory might 
1c2a0 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
1c2b0 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
1c2c0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1c2d0 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  rror..** Memory 
1c2e0 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
1c2f0 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1c300 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
1c310 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
1c320 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
1c330 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
1c340 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
1c350 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
1c360 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
1c370 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1c380 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1c390 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1c3a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1c3b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1c3c0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
1c3d0 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
1c3e0 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
1c3f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20  allocation X to 
1c400 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
1c410 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
1c420 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  X parameter to s
1c430 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1c440 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ,N).** is a NULL
1c450 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
1c460 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
1c470 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
1c480 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
1c490 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20  lloc(N)..** ^If 
1c4a0 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
1c4b0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1c4c0 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20  oc(X,N) is zero 
1c4d0 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
1c4e0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1c4f0 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
1c500 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
1c510 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
1c520 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  X)..** ^sqlite3_
1c530 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74  realloc(X,N) ret
1c540 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1c550 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
1c560 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
1c570 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1c580 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
1c590 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  insufficient mem
1c5a0 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ory is available
1c5b0 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
1c5c0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
1c5d0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
1c5e0 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
1c5f0 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
1c600 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
1c610 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
1c620 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
1c630 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
1c640 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
1c650 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74  alloc(X,N) and t
1c660 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1c670 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
1c680 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61   ^If sqlite3_rea
1c690 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1c6a0 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20  s NULL and N is 
1c6b0 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74  positive, then t
1c6c0 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f  he.** prior allo
1c6d0 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72  cation is not fr
1c6e0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1c6f0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1c700 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  4(X,N) interface
1c710 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65  s works the same
1c720 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   as.** sqlite3_r
1c730 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65  ealloc(X,N) exce
1c740 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36  pt that N is a 6
1c750 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  4-bit unsigned i
1c760 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
1c770 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69  * of a 32-bit si
1c780 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  gned integer..**
1c790 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d  .** ^If X is a m
1c7a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1c7b0 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
1c7c0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1c7d0 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  3_malloc(),.** s
1c7e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1c7f0 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
1c800 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  oc(), or sqlite3
1c810 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68  _realloc64(), th
1c820 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73  en.** sqlite3_ms
1c830 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74  ize(X) returns t
1c840 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20  he size of that 
1c850 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1c860 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  n in bytes..** ^
1c870 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1c880 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73  ed by sqlite3_ms
1c890 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20  ize(X) might be 
1c8a0 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
1c8b0 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74  number.** of byt
1c8c0 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65  es requested whe
1c8d0 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65  n X was allocate
1c8e0 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e  d.  ^If X is a N
1c8f0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1c900 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
1c910 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72  e(X) returns zer
1c920 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20  o.  If X points 
1c930 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61  to something tha
1c940 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20  t is not.** the 
1c950 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d  beginning of mem
1c960 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ory allocation, 
1c970 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20  or if it points 
1c980 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a  to a formerly.**
1c990 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c   valid memory al
1c9a0 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61  location that ha
1c9b0 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64  s now been freed
1c9c0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
1c9d0 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ior.** of sqlite
1c9e0 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e  3_msize(X) is un
1c9f0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73  defined and poss
1ca00 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ibly harmful..**
1ca10 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1ca20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1ca30 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71  te3_malloc(), sq
1ca40 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
1ca50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1ca60 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69  oc64(), and sqli
1ca70 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a  te3_realloc64().
1ca80 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
1ca90 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
1caa0 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
1cab0 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
1cac0 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
1cad0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
1cae0 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
1caf0 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
1cb00 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
1cb10 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
1cb20 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1cb30 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
1cb40 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
1cb50 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
1cb60 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
1cb70 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
1cb80 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
1cb90 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
1cba0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1cbb0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1cbc0 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
1cbd0 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
1cbe0 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
1cbf0 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
1cc00 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1cc10 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
1cc20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  be used..**.** P
1cc30 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
1cc40 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74  ersion 3.7.10, t
1cc50 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
1cc60 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
1cc70 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74  lled.** the syst
1cc80 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
1cc90 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
1cca0 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
1ccb0 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
1ccc0 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
1ccd0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
1cce0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
1ccf0 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
1cd00 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
1cd10 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
1cd20 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
1cd30 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
1cd40 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1cd50 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63  rrors were detec
1cd60 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
1cd70 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62   were reported b
1cd80 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
1cd90 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
1cda0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
1cdb0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1cdc0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
1cdd0 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
1cde0 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
1cdf0 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
1ce00 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1ce10 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
1ce20 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
1ce30 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
1ce40 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
1ce50 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
1ce60 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1ce70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1ce80 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
1ce90 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
1cea0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
1ceb0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
1cec0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
1ced0 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
1cee0 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
1cef0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
1cf00 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
1cf10 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
1cf20 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1cf30 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1cf40 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69  alloc()]..*/.voi
1cf50 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
1cf60 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  c(int);.void *sq
1cf70 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73  lite3_malloc64(s
1cf80 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
1cf90 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
1cfa0 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
1cfb0 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
1cfc0 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a  _realloc64(void*
1cfd0 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
1cfe0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1cff0 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c  free(void*);.sql
1d000 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69  ite3_uint64 sqli
1d010 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29  te3_msize(void*)
1d020 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d030 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
1d040 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a  tor Statistics.*
1d050 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
1d060 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
1d070 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
1d080 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
1d090 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
1d0a0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1d0b0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
1d0c0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
1d0d0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
1d0e0 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
1d0f0 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
1d100 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1d110 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
1d120 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
1d130 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1d140 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1d150 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
1d160 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d   bytes.** of mem
1d170 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
1d180 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
1d190 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
1d1a0 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  d)..** ^The [sql
1d1b0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1d1c0 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
1d1d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
1d1e0 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  imum.** value of
1d1f0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1d200 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
1d210 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1d220 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72  rk.** was last r
1d230 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75  eset.  ^The valu
1d240 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
1d250 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1d260 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
1d270 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1d280 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
1d290 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
1d2a0 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69  ** added by SQLi
1d2b0 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
1d2c0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
1d2d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
1d2e0 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68  ** but not overh
1d2f0 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
1d300 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
1d310 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
1d320 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
1d330 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1d340 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a  )] may call..**.
1d350 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68  ** ^The memory h
1d360 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69  igh-water mark i
1d370 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63  s reset to the c
1d380 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a  urrent value of.
1d390 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1d3a0 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
1d3b0 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
1d3c0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
1d3d0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1d3e0 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72  ghwater()] is tr
1d3f0 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20  ue.  ^The value 
1d400 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b  returned.** by [
1d410 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1d420 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
1d430 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1d440 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ark.** prior to 
1d450 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71  the reset..*/.sq
1d460 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1d470 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1d480 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69  void);.sqlite3_i
1d490 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1d4a0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
1d4b0 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
1d4c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
1d4d0 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
1d4e0 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a  ber Generator.**
1d4f0 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
1d500 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
1d510 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
1d520 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
1d530 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
1d540 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
1d550 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
1d560 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
1d570 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
1d580 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
1d590 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
1d5a0 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
1d5b0 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
1d5c0 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
1d5d0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
1d5e0 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
1d5f0 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
1d600 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
1d610 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
1d620 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
1d630 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
1d640 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
1d650 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
1d660 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61  ses..**.** ^A ca
1d670 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
1d680 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
1d690 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
1d6a0 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
1d6b0 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74  * ^The P paramet
1d6c0 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c  er can be a NULL
1d6d0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1d6e0 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ^If this routine
1d6f0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72   has not been pr
1d700 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20  eviously called 
1d710 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f  or if the previo
1d720 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e  us.** call had N
1d730 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f   less than one o
1d740 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
1d750 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65   for P, then the
1d760 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64   PRNG is.** seed
1d770 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
1d780 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ess obtained fro
1d790 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
1d7a0 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74  s method of.** t
1d7b0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1d7c0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
1d7d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76  .** ^If the prev
1d7e0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69  ious call to thi
1d7f0 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e  s routine had an
1d800 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20   N of 1 or more 
1d810 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c  and a.** non-NUL
1d820 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65  L P then the pse
1d830 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
1d840 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69  s generated.** i
1d850 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69  nternally and wi
1d860 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74  thout recourse t
1d870 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
1d880 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a  fs] xRandomness.
1d890 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f  ** method..*/.vo
1d8a0 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  id sqlite3_rando
1d8b0 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69  mness(int N, voi
1d8c0 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d *P);../*.** CA
1d8d0 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
1d8e0 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
1d8f0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
1d900 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1d910 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75   registers an au
1d920 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1d930 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
1d940 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
1d950 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
1d960 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
1d970 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
1d980 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
1d990 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1d9a0 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
1d9b0 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
1d9c0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
1d9d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1d9e0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1d9f0 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
1da00 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
1da10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1da20 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
1da30 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1da40 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a  ].  ^At various.
1da50 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
1da60 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
1da70 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
1da80 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
1da90 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
1daa0 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
1dab0 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
1dac0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1dad0 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
1dae0 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
1daf0 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e   are allowed.  ^
1db00 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1db10 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
1db20 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
1db30 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68  _OK] to allow th
1db40 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
1db50 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
1db60 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
1db70 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
1db80 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
1db90 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
1dba0 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
1dbb0 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
1dbc0 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
1dbd0 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
1dbe0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
1dbf0 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
1dc00 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66  h an error.  ^If
1dc10 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1dc20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1dc30 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  .** any value ot
1dc40 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1dc50 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
1dc60 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
1dc70 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20  E_DENY].** then 
1dc80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
1dc90 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
1dca0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
1dcb0 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20  at triggered.** 
1dcc0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77  the authorizer w
1dcd0 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
1dce0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
1dcf0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
1dd00 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1dd10 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61  [SQLITE_OK], tha
1dd20 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72  t means the oper
1dd30 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74  ation.** request
1dd40 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e  ed is ok.  ^When
1dd50 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1dd60 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
1dd70 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
1dd80 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1dd90 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
1dda0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
1ddb0 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
1ddc0 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
1ddd0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
1dde0 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
1ddf0 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
1de00 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a   is denied. .**.
1de10 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
1de20 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
1de30 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1de40 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
1de50 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
1de60 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
1de70 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1de80 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
1de90 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
1dea0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
1deb0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
1dec0 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45   integer [SQLITE
1ded0 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
1dee0 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
1def0 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69  ies.** the parti
1df00 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20  cular action to 
1df10 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e  be authorized. ^
1df20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
1df30 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
1df40 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
1df50 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
1df60 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
1df70 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
1df80 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
1df90 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
1dfa0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
1dfb0 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  orized..**.** ^I
1dfc0 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
1dfd0 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
1dfe0 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
1dff0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1e000 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
1e010 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
1e020 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1e030 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
1e040 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
1e050 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
1e060 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
1e070 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
1e080 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
1e090 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
1e0a0 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
1e0b0 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
1e0c0 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
1e0d0 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
1e0e0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
1e0f0 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
1e100 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
1e110 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
1e120 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
1e130 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  le..** ^If the a
1e140 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
1e150 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
1e160 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
1e170 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
1e180 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
1e190 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
1e1a0 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
1e1b0 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
1e1c0 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
1e1d0 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
1e1e0 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
1e1f0 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
1e200 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
1e210 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
1e220 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
1e230 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
1e240 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
1e250 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
1e260 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
1e270 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
1e280 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1e290 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
1e2a0 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
1e2b0 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
1e2c0 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
1e2d0 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
1e2e0 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
1e2f0 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
1e300 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
1e310 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
1e320 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
1e330 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
1e340 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
1e350 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
1e360 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
1e370 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
1e380 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
1e390 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
1e3a0 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
1e3b0 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
1e3c0 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
1e3d0 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
1e3e0 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
1e3f0 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
1e400 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
1e410 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
1e420 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
1e430 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
1e440 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
1e450 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
1e460 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
1e470 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
1e480 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
1e490 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
1e4a0 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
1e4b0 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
1e4c0 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
1e4d0 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
1e4e0 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
1e4f0 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
1e500 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
1e510 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
1e520 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
1e530 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
1e540 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
1e550 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
1e560 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
1e570 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
1e580 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
1e590 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
1e5a0 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
1e5b0 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
1e5c0 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
1e5d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1e5e0 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
1e5f0 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
1e600 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1e610 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
1e620 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
1e630 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
1e640 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
1e650 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
1e660 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
1e670 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
1e680 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
1e690 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
1e6a0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1e6b0 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
1e6c0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
1e6d0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
1e6e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1e6f0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1e700 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
1e710 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
1e720 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
1e730 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
1e740 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
1e750 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
1e760 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
1e770 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
1e780 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
1e790 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
1e7a0 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
1e7b0 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
1e7c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1e7d0 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
1e7e0 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
1e7f0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
1e800 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
1e810 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
1e820 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
1e830 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
1e840 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
1e850 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
1e860 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
1e870 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
1e880 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
1e890 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
1e8a0 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
1e8b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
1e8c0 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
1e8d0 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
1e8e0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1e8f0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
1e900 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
1e910 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
1e920 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
1e930 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
1e940 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
1e950 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
1e960 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
1e970 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1e980 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
1e990 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
1e9a0 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
1e9b0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
1e9c0 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
1e9d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
1e9e0 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
1e9f0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
1ea00 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
1ea10 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
1ea20 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
1ea30 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
1ea40 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
1ea50 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
1ea60 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1ea70 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1ea80 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
1ea90 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
1eaa0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
1eab0 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
1eac0 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
1ead0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1eae0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1eaf0 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
1eb00 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
1eb10 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
1eb20 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
1eb30 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
1eb40 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
1eb50 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
1eb60 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
1eb70 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
1eb80 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
1eb90 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1eba0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
1ebb0 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
1ebc0 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
1ebd0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
1ebe0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
1ebf0 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45  Note that SQLITE
1ec00 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20  _IGNORE is also 
1ec10 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c  used as a [confl
1ec20 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d  ict resolution m
1ec30 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ode].** returned
1ec40 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
1ec50 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
1ec60 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ict()] interface
1ec70 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
1ec80 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
1ec90 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
1eca0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
1ecb0 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
1ecc0 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
1ecd0 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
1ece0 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
1ecf0 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
1ed00 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
1ed10 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
1ed20 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
1ed30 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
1ed40 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1ed50 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
1ed60 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
1ed70 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1ed80 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
1ed90 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
1eda0 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
1edb0 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
1edc0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
1edd0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1ede0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1edf0 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
1ee00 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
1ee10 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
1ee20 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
1ee30 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
1ee40 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
1ee50 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
1ee60 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1ee70 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
1ee80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
1ee90 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
1eea0 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
1eeb0 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
1eec0 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
1eed0 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
1eee0 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
1eef0 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
1ef00 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
1ef10 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
1ef20 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
1ef30 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
1ef40 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
1ef50 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
1ef60 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
1ef70 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
1ef80 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  ^(The 5th parame
1ef90 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
1efa0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1efb0 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
1efc0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
1efd0 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
1efe0 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
1eff0 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36  cable.)^  ^The 6
1f000 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1f010 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1f020 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
1f030 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
1f040 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
1f050 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
1f060 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
1f070 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
1f080 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
1f090 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
1f0a0 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
1f0b0 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
1f0c0 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
1f0d0 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
1f0e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f0f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
1f100 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
1f110 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
1f120 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1f130 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
1f140 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
1f150 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1f160 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1f170 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1f180 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
1f190 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
1f1a0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1f1b0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f1c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1f1d0 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
1f1e0 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
1f1f0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1f200 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1f210 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1f220 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
1f230 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
1f240 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1f250 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f260 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1f270 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
1f280 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
1f290 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1f2a0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1f2b0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1f2c0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
1f2d0 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
1f2e0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1f2f0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f300 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1f310 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
1f320 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1f330 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1f340 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f350 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
1f360 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
1f370 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1f380 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f390 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f3a0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
1f3b0 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
1f3c0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1f3d0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f3e0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f3f0 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
1f400 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
1f410 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1f420 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1f430 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f440 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
1f450 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
1f460 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1f470 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f480 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f490 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
1f4a0 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
1f4b0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1f4c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f4d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f4e0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
1f4f0 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
1f500 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f510 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f520 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f530 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
1f540 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
1f550 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1f560 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1f570 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f580 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
1f590 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
1f5a0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1f5b0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f5c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f5d0 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
1f5e0 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
1f5f0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1f600 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1f610 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1f620 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
1f630 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
1f640 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1f650 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f660 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
1f670 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
1f680 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
1f690 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1f6a0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f6b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
1f6c0 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
1f6d0 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
1f6e0 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
1f6f0 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
1f700 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
1f710 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1f720 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
1f730 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
1f740 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1f750 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
1f760 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
1f770 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
1f780 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
1f790 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1f7a0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
1f7b0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
1f7c0 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
1f7d0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1f7e0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f7f0 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
1f800 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
1f810 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1f820 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
1f830 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1f840 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
1f850 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
1f860 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
1f870 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f880 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f890 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
1f8a0 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
1f8b0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
1f8c0 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
1f8d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f8e0 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
1f8f0 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
1f900 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
1f910 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1f920 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f930 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
1f940 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
1f950 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1f960 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f970 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f980 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
1f990 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
1f9a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f9b0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f9c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f9d0 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
1f9e0 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
1f9f0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1fa00 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
1fa10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1fa20 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
1fa30 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
1fa40 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
1fa50 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
1fa60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1fa70 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
1fa80 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
1fa90 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
1faa0 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
1fab0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fac0 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
1fad0 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
1fae0 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
1faf0 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
1fb00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1fb10 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
1fb20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
1fb30 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64  onger used */.#d
1fb40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43  efine SQLITE_REC
1fb50 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20  URSIVE          
1fb60 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    33   /* NULL  
1fb70 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
1fb80 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a            */../*
1fb90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
1fba0 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
1fbb0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
1fbc0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1fbd0 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
1fbe0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
1fbf0 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
1fc00 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
1fc10 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
1fc20 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
1fc30 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
1fc40 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
1fc50 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
1fc60 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
1fc70 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
1fc80 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
1fc90 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
1fca0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
1fcb0 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
1fcc0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
1fcd0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1fce0 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
1fcf0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
1fd00 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
1fd10 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
1fd20 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
1fd30 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
1fd40 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
1fd50 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
1fd60 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
1fd70 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
1fd80 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
1fd90 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
1fda0 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
1fdb0 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
1fdc0 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
1fdd0 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
1fde0 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
1fdf0 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
1fe00 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
1fe10 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  r.)^.**.** The [
1fe20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a  SQLITE_TRACE_SIZ
1fe30 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65  E_LIMIT] compile
1fe40 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e  -time option can
1fe50 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69   be used to limi
1fe60 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20  t.** the length 
1fe70 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  of [bound parame
1fe80 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69  ter] expansion i
1fe90 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20  n the output of 
1fea0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e  sqlite3_trace().
1feb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
1fec0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
1fed0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
1fee0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
1fef0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
1ff00 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
1ff10 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
1ff20 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
1ff30 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
1ff40 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
1ff50 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
1ff60 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
1ff70 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
1ff80 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
1ff90 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
1ffa0 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70   to run.  ^The p
1ffb0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a  rofile callback.
1ffc0 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e  ** time is in un
1ffd0 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  its of nanosecon
1ffe0 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  ds, however the 
1fff0 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
20000 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c  tation.** is onl
20010 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c  y capable of mil
20020 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74  lisecond resolut
20030 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c  ion so the six l
20040 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
20050 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68  .** digits in th
20060 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69  e time are meani
20070 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20  ngless.  Future 
20080 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
20090 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76  te.** might prov
200a0 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f  ide greater reso
200b0 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72  lution on the pr
200c0 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  ofiler callback.
200d0 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
200e0 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74  _profile() funct
200f0 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ion is considere
20100 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
20110 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74  nd is.** subject
20120 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
20130 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
20140 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64   SQLite..*/.void
20150 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
20160 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
20170 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
20180 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
20190 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  *);.SQLITE_EXPER
201a0 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71  IMENTAL void *sq
201b0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
201c0 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
201d0 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
201e0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
201f0 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
20200 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
20210 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
20220 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a  gress Callbacks.
20230 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
20240 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
20250 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74  ler(D,N,X,P) int
20260 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
20270 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
20280 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69  nction X to be i
20290 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
202a0 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
202b0 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
202c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
202d0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
202e0 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tep()] and [sqli
202f0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
20300 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65   for.** database
20310 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
20320 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
20330 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
20340 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
20350 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
20360 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
20370 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ry..**.** ^The p
20380 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61  arameter P is pa
20390 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
203a0 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
203b0 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61  er to the .** ca
203c0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
203d0 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  X.  ^The paramet
203e0 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72  er N is the appr
203f0 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f  oximate number o
20400 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d  f .** [virtual m
20410 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69  achine instructi
20420 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76  ons] that are ev
20430 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20  aluated between 
20440 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e  successive.** in
20450 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
20460 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49   callback X.  ^I
20470 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
20480 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72   one then the pr
20490 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65  ogress.** handle
204a0 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a  r is disabled..*
204b0 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e  *.** ^Only a sin
204c0 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  gle progress han
204d0 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69  dler may be defi
204e0 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20  ned at one time 
204f0 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  per.** [database
20500 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65   connection]; se
20510 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67  tting a new prog
20520 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e  ress handler can
20530 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20  cels the.** old 
20540 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70  one.  ^Setting p
20550 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55  arameter X to NU
20560 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  LL disables the 
20570 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
20580 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65  ..** ^The progre
20590 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c  ss handler is al
205a0 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73  so disabled by s
205b0 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61  etting N to a va
205c0 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e  lue less.** than
205d0 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   1..**.** ^If th
205e0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
205f0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
20600 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
20610 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
20620 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
20630 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
20640 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
20650 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
20660 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
20670 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
20680 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
20690 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  ess handler call
206a0 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
206b0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
206c0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
206d0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
206e0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
206f0 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
20700 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
20710 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
20720 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
20730 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
20740 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
20750 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
20760 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
20770 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
20780 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
20790 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f  paragraph..**.*/
207a0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72  .void sqlite3_pr
207b0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
207c0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
207d0 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
207e0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
207f0 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
20800 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
20810 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  nection.**.** ^T
20820 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
20830 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
20840 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70  abase file as sp
20850 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ecified by the .
20860 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
20870 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e  ment. ^The filen
20880 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
20890 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
208a0 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
208b0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
208c0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
208d0 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
208e0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
208f0 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
20900 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
20910 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63   ^(A [database c
20920 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
20930 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
20940 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
20950 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
20960 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
20970 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
20980 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
20990 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
209a0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
209b0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
209c0 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
209d0 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
209e0 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
209f0 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
20a00 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
20a10 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
20a20 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65  ject.)^ ^(If the
20a30 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
20a40 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
20a50 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
20a60 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
20a70 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
20a80 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
20a90 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
20aa0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54  s returned.)^ ^T
20ab0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
20ac0 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
20ad0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
20ae0 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
20af0 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
20b00 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
20b10 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
20b20 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  on of the error 
20b30 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
20b40 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ure of any.** of
20b50 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   the sqlite3_ope
20b60 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  n() routines..**
20b70 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
20b80 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62   encoding will b
20b90 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61  e UTF-8 for data
20ba0 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73  bases created us
20bb0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  ing.** sqlite3_o
20bc0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
20bd0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68  _open_v2().  ^Th
20be0 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
20bf0 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73  ng for databases
20c00 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e  .** created usin
20c10 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  g sqlite3_open16
20c20 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31  () will be UTF-1
20c30 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
20c40 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a  byte order..**.*
20c50 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
20c60 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
20c70 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
20c80 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
20c90 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
20ca0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
20cb0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
20cc0 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
20cd0 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
20ce0 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
20cf0 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
20d00 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
20d10 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
20d20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
20d30 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
20d40 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
20d50 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
20d60 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
20d70 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
20d80 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
20d90 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
20da0 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
20db0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
20dc0 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65  nnection.  ^(The
20dd0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
20de0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   to.** sqlite3_o
20df0 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b  pen_v2() can tak
20e00 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
20e10 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
20e20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
20e30 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
20e40 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
20e50 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
20e60 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
20e70 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  LMUTEX], [SQLITE
20e80 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
20e90 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  E],.** [SQLITE_O
20ea0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
20eb0 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ], and/or [SQLIT
20ec0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
20ed0 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
20ee0 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
20ef0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
20f00 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
20f10 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
20f20 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
20f30 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
20f40 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
20f50 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
20f60 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
20f70 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
20f80 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
20f90 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
20fa0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
20fb0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
20fc0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
20fd0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
20fe0 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
20ff0 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
21000 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
21010 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
21020 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
21030 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
21040 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
21050 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
21060 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
21070 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
21080 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
21090 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
210a0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
210b0 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
210c0 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
210d0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
210e0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
210f0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
21100 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
21110 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20  reated if.** it 
21120 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
21130 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
21140 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
21150 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
21160 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
21170 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
21180 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
21190 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  >)^.** </dl>.**.
211a0 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
211b0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
211c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
211d0 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
211e0 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
211f0 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f  hown above optio
21200 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
21210 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51  ith other.** [SQ
21220 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
21230 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e  LY | SQLITE_OPEN
21240 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e  _* bits].** then
21250 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
21260 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
21270 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
21280 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
21290 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65  flag is set, the
212a0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
212b0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65  onnection.** ope
212c0 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d  ns in the multi-
212d0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
212e0 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20  g mode] as long 
212f0 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68  as the single-th
21300 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73  read.** mode has
21310 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74   not been set at
21320 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
21330 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49   start-time.  ^I
21340 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
21350 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
21360 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
21370 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
21380 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
21390 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
213a0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
213b0 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
213c0 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
213d0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
213e0 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
213f0 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
21400 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ime..** ^The [SQ
21410 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
21420 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
21430 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
21440 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65  connection to be
21450 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20  .** eligible to 
21460 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68  use [shared cach
21470 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c  e mode], regardl
21480 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
21490 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20  r not shared.** 
214a0 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
214b0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
214c0 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
214d0 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a  che()].  ^The.**
214e0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
214f0 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
21500 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
21510 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
21520 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63  to not.** partic
21530 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64  ipate in [shared
21540 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65   cache mode] eve
21550 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c  n if it is enabl
21560 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
21570 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
21580 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
21590 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
215a0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
215b0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
215c0 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
215d0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
215e0 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
215f0 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
21600 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
21610 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66  should use.  ^If
21620 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
21630 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
21640 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
21650 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
21660 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
21670 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
21680 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
21690 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
216a0 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
216b0 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
216c0 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
216d0 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
216e0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
216f0 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
21700 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
21710 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
21720 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21730 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
21740 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
21750 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
21760 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
21770 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
21780 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
21790 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
217a0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
217b0 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
217c0 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
217d0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
217e0 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
217f0 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
21800 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
21810 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
21820 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
21830 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
21840 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
21850 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
21860 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
21870 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
21880 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
21890 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
218a0 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
218b0 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
218c0 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
218d0 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
218e0 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
218f0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
21900 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
21910 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
21920 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
21930 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  d..**.** [[URI f
21940 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69  ilenames in sqli
21950 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33  te3_open()]] <h3
21960 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f  >URI Filenames</
21970 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55  h3>.**.** ^If [U
21980 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74  RI filename] int
21990 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
219a0 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20  nabled, and the 
219b0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
219c0 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68  t.** begins with
219d0 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74   "file:", then t
219e0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69  he filename is i
219f0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
21a00 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c  URI. ^URI.** fil
21a10 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
21a20 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20  tion is enabled 
21a30 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
21a40 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
21a50 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66  .** set in the f
21a60 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
21a70 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
21a80 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61  2(), or if it ha
21a90 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65  s.** been enable
21aa0 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67  d globally using
21ab0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
21ac0 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20  FIG_URI] option 
21ad0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  with the.** [sql
21ae0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d  ite3_config()] m
21af0 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20  ethod or by the 
21b00 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
21b10 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
21b20 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53  tion..** As of S
21b30 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
21b40 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d  7.7, URI filenam
21b50 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
21b60 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a   is turned off.*
21b70 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75  * by default, bu
21b80 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  t future release
21b90 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
21ba0 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c  t enable URI fil
21bb0 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72  ename.** interpr
21bc0 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75  etation by defau
21bd0 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66  lt.  See "[URI f
21be0 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61  ilenames]" for a
21bf0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
21c00 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
21c10 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  URI filenames ar
21c20 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69  e parsed accordi
21c30 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20  ng to RFC 3986. 
21c40 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74  ^If the URI cont
21c50 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f  ains an.** autho
21c60 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75  rity, then it mu
21c70 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20  st be either an 
21c80 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
21c90 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22  the string .** "
21ca0 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20  localhost". ^If 
21cb0 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73  the authority is
21cc0 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74   not an empty st
21cd0 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f  ring or "localho
21ce0 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f  st", an .** erro
21cf0 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f  r is returned to
21d00 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68   the caller. ^Th
21d10 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f  e fragment compo
21d20 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69  nent of a URI, i
21d30 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69  f .** present, i
21d40 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
21d50 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
21d60 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74  e path component
21d70 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74   of the URI as t
21d80 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
21d90 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63  isk file.** whic
21da0 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  h contains the d
21db0 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65  atabase. ^If the
21dc0 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74   path begins wit
21dd0 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65  h a '/' characte
21de0 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  r, .** then it i
21df0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
21e00 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
21e10 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  h. ^If the path 
21e20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a  does not begin .
21e30 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d  ** with a '/' (m
21e40 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20  eaning that the 
21e50 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f  authority sectio
21e60 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  n is omitted fro
21e70 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68  m the URI).** th
21e80 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69  en the path is i
21e90 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
21ea0 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a  relative path. .
21eb0 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c  ** ^(On windows,
21ec0 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f   the first compo
21ed0 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c  nent of an absol
21ee0 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20  ute path .** is 
21ef0 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63  a drive specific
21f00 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22  ation (e.g. "C:"
21f10 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72  ).)^.**.** [[cor
21f20 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61  e URI query para
21f30 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20  meters]].** The 
21f40 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
21f50 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e  of a URI may con
21f60 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tain parameters 
21f70 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72  that are interpr
21f80 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62  eted.** either b
21f90 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c  y SQLite itself,
21fa0 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20   or by a [VFS | 
21fb0 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65  custom VFS imple
21fc0 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53  mentation]..** S
21fd0 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75  QLite and its bu
21fe0 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69  ilt-in [VFSes] i
21ff0 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20  nterpret the.** 
22000 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20  following query 
22010 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a  parameters:.**.*
22020 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e  * <ul>.**   <li>
22030 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68   <b>vfs</b>: ^Th
22040 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65  e "vfs" paramete
22050 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  r may be used to
22060 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d   specify the nam
22070 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46  e of.**     a VF
22080 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72  S object that pr
22090 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61  ovides the opera
220a0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
220b0 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c  rface that shoul
220c0 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64  d.**     be used
220d0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
220e0 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20  atabase file on 
220f0 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f  disk. ^If this o
22100 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a  ption is set to.
22110 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20  **     an empty 
22120 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75  string the defau
22130 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73  lt VFS object is
22140 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69   used. ^Specifyi
22150 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a  ng an unknown.**
22160 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65       VFS is an e
22170 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65  rror. ^If sqlite
22180 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
22190 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20  sed and the vfs 
221a0 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
221b0 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74   present, then t
221c0 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64  he VFS specified
221d0 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74   by the option t
221e0 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20  akes precedence 
221f0 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20  over.**     the 
22200 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
22210 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
22220 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
22230 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
22240 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c     <li> <b>mode<
22250 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20  /b>: ^(The mode 
22260 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
22270 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
22280 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20  ro", "rw",.**   
22290 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d    "rwc", or "mem
222a0 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67  ory". Attempting
222b0 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e   to set it to an
222c0 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73  y other value is
222d0 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72  .**     an error
222e0 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20  )^. .**     ^If 
222f0 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65  "ro" is specifie
22300 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  d, then the data
22310 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
22320 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a  or read-only .**
22330 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73       access, jus
22340 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c  t as if the [SQL
22350 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
22360 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e  Y] flag had been
22370 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20   set in the .** 
22380 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65      third argume
22390 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
223a0 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65  en_v2(). ^If the
223b0 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20   mode option is 
223c0 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22  set to .**     "
223d0 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61  rw", then the da
223e0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
223f0 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20   for read-write 
22400 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29  (but not create)
22410 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
22420 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50   as if SQLITE_OP
22430 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75  EN_READWRITE (bu
22440 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45  t not SQLITE_OPE
22450 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a  N_CREATE) had .*
22460 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20  *     been set. 
22470 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20  ^Value "rwc" is 
22480 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
22490 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20  tting both .**  
224a0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52     SQLITE_OPEN_R
224b0 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c  EADWRITE and SQL
224c0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e  ITE_OPEN_CREATE.
224d0 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f    ^If the mode o
224e0 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
224f0 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20  set to "memory" 
22500 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d  then a pure [in-
22510 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d  memory database]
22520 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64   that never read
22530 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74  s.**     or writ
22540 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20  es from disk is 
22550 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20  used. ^It is an 
22560 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79  error to specify
22570 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20   a value for.** 
22580 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72      the mode par
22590 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c  ameter that is l
225a0 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20  ess restrictive 
225b0 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66  than that specif
225c0 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68  ied by.**     th
225d0 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69  e flags passed i
225e0 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
225f0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
22600 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
22610 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68  *   <li> <b>cach
22620 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68  e</b>: ^The cach
22630 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
22640 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
22650 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20   "shared" or.** 
22660 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e      "private". ^
22670 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73  Setting it to "s
22680 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61  hared" is equiva
22690 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
226a0 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  the.**     SQLIT
226b0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
226c0 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c  HE bit in the fl
226d0 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ags argument pas
226e0 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71  sed to.**     sq
226f0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
22700 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61   ^Setting the ca
22710 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  che parameter to
22720 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a   "private" is .*
22730 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74  *     equivalent
22740 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20   to setting the 
22750 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
22760 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a  ATECACHE bit..**
22770 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33       ^If sqlite3
22780 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
22790 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68  ed and the "cach
227a0 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e" parameter is 
227b0 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20  present in.**   
227c0 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65    a URI filename
227d0 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72  , its value over
227e0 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69  rides any behavi
227f0 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20  or requested by 
22800 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53  setting.**     S
22810 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
22820 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54  TECACHE or SQLIT
22830 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
22840 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20  HE flag..**.**  
22850 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e  <li> <b>psow</b>
22860 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61  : ^The psow para
22870 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20  meter indicates 
22880 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
22890 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72  he.**     [power
228a0 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20  safe overwrite] 
228b0 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72  property does or
228c0 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20   does not apply 
228d0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74  to the.**     st
228e0 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77  orage media on w
228f0 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73  hich the databas
22900 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a  e file resides..
22910 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e  **.**  <li> <b>n
22920 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20  olock</b>: ^The 
22930 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72  nolock parameter
22940 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
22950 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ery parameter.**
22960 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65       which if se
22970 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20  t disables file 
22980 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62  locking in rollb
22990 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65  ack journal mode
229a0 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20  s.  This.**     
229b0 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63  is useful for ac
229c0 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61  cessing a databa
229d0 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74  se on a filesyst
229e0 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  em that does not
229f0 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20  .**     support 
22a00 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f  locking.  Cautio
22a10 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72  n:  Database cor
22a20 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ruption might re
22a30 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20  sult if two.**  
22a40 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65     or more proce
22a50 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68  sses write to th
22a60 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
22a70 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74  and any one of t
22a80 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63  hose.**     proc
22a90 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63  esses uses noloc
22aa0 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  k=1..**.**  <li>
22ab0 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62   <b>immutable</b
22ac0 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c  >: ^The immutabl
22ad0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  e parameter is a
22ae0 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a   boolean query.*
22af0 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20  *     parameter 
22b00 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74  that indicates t
22b10 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
22b20 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20   file is stored 
22b30 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f  on.**     read-o
22b40 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65  nly media.  ^Whe
22b50 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73  n immutable is s
22b60 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d  et, SQLite assum
22b70 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20  es that the.**  
22b80 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65     database file
22b90 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
22ba0 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72  ed, even by a pr
22bb0 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65  ocess with highe
22bc0 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65  r.**     privile
22bd0 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64  ge, and so the d
22be0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
22bf0 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20  d read-only and 
22c00 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20  all locking.**  
22c10 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65     and change de
22c20 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62  tection is disab
22c30 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53  led.  Caution: S
22c40 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74  etting the immut
22c50 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70  able.**     prop
22c60 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61  erty on a databa
22c70 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65  se file that doe
22c80 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65  s in fact change
22c90 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20   can result.**  
22ca0 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20     in incorrect 
22cb0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e  query results an
22cc0 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52  d/or [SQLITE_COR
22cd0 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a  RUPT] errors..**
22ce0 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b       See also: [
22cf0 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
22d00 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20  UTABLE]..**     
22d10 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a    .** </ul>.**.*
22d20 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  * ^Specifying an
22d30 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74   unknown paramet
22d40 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  er in the query 
22d50 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
22d60 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20  RI is not an.** 
22d70 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76  error.  Future v
22d80 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
22d90 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61  e might understa
22da0 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75  nd additional qu
22db0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
22dc0 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20  s.  See "[query 
22dd0 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20  parameters with 
22de0 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20  special meaning 
22df0 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a  to SQLite]" for.
22e00 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
22e10 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
22e20 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20   [[URI filename 
22e30 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55  examples]] <h3>U
22e40 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
22e50 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ples</h3>.**.** 
22e60 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
22e70 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63  " align=center c
22e80 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a  ellpadding=5>.**
22e90 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69   <tr><th> URI fi
22ea0 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73  lenames <th> Res
22eb0 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ults.** <tr><td>
22ec0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74   file:data.db <t
22ed0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
22ee0 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
22ef0 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
22f00 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
22f10 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
22f20 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
22f30 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20  ta.db<br>.**    
22f40 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f        file:///ho
22f50 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
22f60 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <br> .**        
22f70 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f    file://localho
22f80 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  st/home/fred/dat
22f90 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a  a.db <br> <td> .
22fa0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
22fb0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
22fc0 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
22fd0 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e  ata.db"..** <tr>
22fe0 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b  <td> file://dark
22ff0 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  star/home/fred/d
23000 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
23010 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
23020 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73  r. "darkstar" is
23030 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65   not a recognize
23040 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20  d authority..** 
23050 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77  <tr><td style="w
23060 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61  hite-space:nowra
23070 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  p"> .**         
23080 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75   file:///C:/Docu
23090 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65  ments%20and%20Se
230a0 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b  ttings/fred/Desk
230b0 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20  top/data.db.**  
230c0 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20     <td> Windows 
230d0 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66  only: Open the f
230e0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e  ile "data.db" on
230f0 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20   fred's desktop 
23100 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20  on drive.**     
23110 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68       C:. Note th
23120 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70  at the %20 escap
23130 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d  ing in this exam
23140 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63  ple is not stric
23150 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  tly .**         
23160 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61   necessary - spa
23170 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61  ce characters ca
23180 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61  n be used litera
23190 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lly.**          
231a0 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  in URI filenames
231b0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
231c0 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
231d0 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65  ro&cache=private
231e0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
231f0 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61     Open file "da
23200 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
23210 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20  rrent directory 
23220 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63  for read-only ac
23230 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20  cess..**        
23240 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20    Regardless of 
23250 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
23260 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65  hared-cache mode
23270 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a   is enabled by.*
23280 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
23290 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74  lt, use a privat
232a0 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e  e cache..** <tr>
232b0 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
232c0 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73  fred/data.db?vfs
232d0 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74  =unix-dotfile <t
232e0 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
232f0 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
23300 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
23310 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
23320 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65  FS "unix-dotfile
23330 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ".**          th
23340 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65  at uses dot-file
23350 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f  s in place of po
23360 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63  six advisory loc
23370 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  king..** <tr><td
23380 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
23390 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64  ode=readonly <td
233a0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
233b0 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e  n error. "readon
233c0 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c  ly" is not a val
233d0 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68  id option for th
233e0 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74  e "mode" paramet
233f0 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  er..** </table>.
23400 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64  **.** ^URI hexad
23410 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
23420 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72  quences (%HH) ar
23430 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  e supported with
23440 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a  in the path and.
23450 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  ** query compone
23460 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20  nts of a URI. A 
23470 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
23480 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73  pe sequence cons
23490 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72  ists of a.** per
234a0 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20  cent sign - "%" 
234b0 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78  - followed by ex
234c0 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65  actly two hexade
234d0 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a  cimal digits .**
234e0 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f   specifying an o
234f0 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66  ctet value. ^Bef
23500 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20  ore the path or 
23510 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
23520 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c   of a.** URI fil
23530 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70  ename are interp
23540 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20  reted, they are 
23550 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
23560 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20  F-8 and all .** 
23570 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
23580 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70  pe sequences rep
23590 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c  laced by a singl
235a0 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e  e byte containin
235b0 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70  g the.** corresp
235c0 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66  onding octet. If
235d0 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65   this process ge
235e0 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c  nerates an inval
235f0 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  id UTF-8 encodin
23600 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  g,.** the result
23610 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
23620 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
23630 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
23640 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
23650 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
23660 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
23670 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
23680 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
23690 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
236a0 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
236b0 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
236c0 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
236d0 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
236e0 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
236f0 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
23700 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
23710 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
23720 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
23730 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
23740 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
23750 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
23760 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
23770 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
23780 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
23790 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
237a0 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
237b0 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
237c0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
237d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
237e0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
237f0 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  2().  Otherwise,
23800 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
23810 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
23820 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
23830 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
23840 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   fail..**.** See
23850 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
23860 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a  temp_directory].
23870 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
23880 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
23890 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
238a0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
238b0 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
238c0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
238d0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
238e0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
238f0 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
23900 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
23910 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
23920 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
23930 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
23940 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
23950 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
23960 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
23970 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
23980 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
23990 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
239a0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
239b0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
239c0 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
239d0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
239e0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
239f0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
23a00 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
23a10 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
23a20 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
23a30 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
23a40 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
23a50 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
23a60 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
23a70 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
23a80 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50  Values For URI P
23a90 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
23aa0 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74  These are utilit
23ab0 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66  y routines, usef
23ac0 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d  ul to VFS implem
23ad0 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20  entations, that 
23ae0 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20  check.** to see 
23af0 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69  if a database fi
23b00 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61  le was a URI tha
23b10 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70  t contained a sp
23b20 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a  ecific query .**
23b30 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20   parameter, and 
23b40 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68  if so obtains th
23b50 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
23b60 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e  query parameter.
23b70 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74  .**.** If F is t
23b80 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
23b90 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
23ba0 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
23bb0 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a  en() method of .
23bc0 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65  ** a VFS impleme
23bd0 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  ntation when the
23be0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
23bf0 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20   to xOpen() has 
23c00 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20  one or .** more 
23c10 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  of the [SQLITE_O
23c20 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c  PEN_URI] or [SQL
23c30 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
23c40 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a  ] bits set and.*
23c50 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20  * P is the name 
23c60 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
23c70 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ameter, then.** 
23c80 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
23c90 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
23ca0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
23cb0 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74  the P.** paramet
23cc0 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20  er if it exists 
23cd0 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
23ce0 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20  r if P does not 
23cf0 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20  appear as a .** 
23d00 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
23d10 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61  on F.  If P is a
23d20 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
23d30 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20   of F.** has no 
23d40 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20  explicit value, 
23d50 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
23d60 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
23d70 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69  returns.** a poi
23d80 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79  nter to an empty
23d90 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
23da0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
23db0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
23dc0 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68  utine assumes th
23dd0 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61  at P is a boolea
23de0 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61  n.** parameter a
23df0 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  nd returns true 
23e00 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29  (1) or false (0)
23e10 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68   according to th
23e20 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e  e value.** of P.
23e30 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72    The sqlite3_ur
23e40 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
23e50 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
23e60 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65   true (1) if the
23e70 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65  .** value of que
23e80 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
23e90 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20  s one of "yes", 
23ea0 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20  "true", or "on" 
23eb0 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f  in any.** case o
23ec0 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  r if the value b
23ed0 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e  egins with a non
23ee0 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54  -zero number.  T
23ef0 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  he .** sqlite3_u
23f00 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
23f10 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  ) routines retur
23f20 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20  ns false (0) if 
23f30 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
23f40 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
23f50 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22  P is one of "no"
23f60 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f  , "false", or "o
23f70 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20  ff" in any case 
23f80 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c  or.** if the val
23f90 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
23fa0 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20   numeric zero.  
23fb0 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75  If P is not a qu
23fc0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
23fd0 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20   on F or if the 
23fe0 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f  value of P is do
23ff0 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79  es not match any
24000 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65   of the.** above
24010 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
24020 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
24030 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29  ) returns (B!=0)
24040 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
24050 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c  te3_uri_int64(F,
24060 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e  P,D) routine con
24070 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20  verts the value 
24080 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36  of P into a.** 6
24090 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
240a0 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eger and returns
240b0 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f   that integer, o
240c0 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  r D if P does no
240d0 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20  t.** exist.  If 
240e0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
240f0 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  s something othe
24100 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65  r than an intege
24110 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20  r, then.** zero 
24120 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
24130 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55  .** If F is a NU
24140 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
24150 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
24160 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
24170 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20  rns NULL and.** 
24180 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
24190 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
241a0 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e  ns B.  If F is n
241b0 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ot a NULL pointe
241c0 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20  r and.** is not 
241d0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
241e0 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72  pathname pointer
241f0 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73   that SQLite pas
24200 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
24210 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64  en.** VFS method
24220 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
24230 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
24240 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
24250 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a   and probably.**
24260 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
24270 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
24280 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
24290 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
242a0 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
242b0 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69  char *zParam);.i
242c0 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  nt sqlite3_uri_b
242d0 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61  oolean(const cha
242e0 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20  r *zFile, const 
242f0 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e  char *zParam, in
24300 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c  t bDefault);.sql
24310 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
24320 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e  e3_uri_int64(con
24330 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20  st char*, const 
24340 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  char*, sqlite3_i
24350 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt64);.../*.** C
24360 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
24370 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
24380 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
24390 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
243a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
243b0 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
243c0 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  sult code] or.**
243d0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
243e0 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  t code] for the 
243f0 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c  most recent fail
24400 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  ed sqlite3_* API
24410 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61   call.** associa
24420 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61  ted with a [data
24430 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
24440 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49  . If a prior API
24450 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20   call failed.** 
24460 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  but the most rec
24470 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63  ent API call suc
24480 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75  ceeded, the retu
24490 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a  rn value from.**
244a0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
244b0 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
244c0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65    ^The sqlite3_e
244d0 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
244e0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
244f0 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70  s the same excep
24500 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73  t that it always
24510 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a   returns the .**
24520 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
24530 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65  t code] even whe
24540 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
24550 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64  t codes are.** d
24560 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
24570 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  The sqlite3_errm
24580 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  sg() and sqlite3
24590 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75  _errmsg16() retu
245a0 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
245b0 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74  age.** text that
245c0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
245d0 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20  rror, as either 
245e0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
245f0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
24600 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
24610 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
24620 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
24630 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
24640 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
24650 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
24660 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75  ed to worry abou
24670 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  t freeing the re
24680 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
24690 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
246a0 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
246b0 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
246c0 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
246d0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
246e0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
246f0 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
24700 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s.)^.**.** ^The 
24710 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29  sqlite3_errstr()
24720 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
24730 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c  ns the English-l
24740 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20  anguage text.** 
24750 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
24760 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  he [result code]
24770 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e  , as UTF-8..** ^
24780 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
24790 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
247a0 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
247b0 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a  ged internally.*
247c0 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62  * and must not b
247d0 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61  e freed by the a
247e0 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a  pplication)^..**
247f0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
24800 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
24810 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
24820 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
24830 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
24840 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
24850 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
24860 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
24870 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
24880 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
24890 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
248a0 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
248b0 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
248c0 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
248d0 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
248e0 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
248f0 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
24900 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
24910 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
24920 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
24930 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
24940 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
24950 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
24960 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
24970 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24980 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
24990 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
249a0 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
249b0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
249c0 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
249d0 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
249e0 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
249f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
24a00 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
24a10 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
24a20 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
24a30 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
24a40 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
24a50 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
24a60 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
24a70 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
24a80 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
24a90 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
24aa0 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
24ab0 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
24ac0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
24ad0 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
24ae0 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
24af0 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
24b00 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
24b10 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c   set..*/.int sql
24b20 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
24b30 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73  ite3 *db);.int s
24b40 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
24b50 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
24b60 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
24b70 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
24b80 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
24b90 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
24ba0 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
24bb0 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  *);.const char *
24bc0 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69  sqlite3_errstr(i
24bd0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
24be0 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d  3REF: SQL Statem
24bf0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  ent Object.** KE
24c00 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65  YWORDS: {prepare
24c10 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72  d statement} {pr
24c20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24c30 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
24c40 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
24c50 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
24c60 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
24c70 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  ement..** This o
24c80 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73  bject is various
24c90 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70  ly known as a "p
24ca0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24cb0 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70  t" or a.** "comp
24cc0 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
24cd0 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73  nt" or simply as
24ce0 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a   a "statement"..
24cf0 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f  **.** The life o
24d00 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  f a statement ob
24d10 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68  ject goes someth
24d20 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ing like this:.*
24d30 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
24d40 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a  > Create the obj
24d50 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
24d60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
24d70 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a   or a related.**
24d80 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a        function..
24d90 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c  ** <li> Bind val
24da0 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72  ues to [host par
24db0 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74  ameters] using t
24dc0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
24dd0 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65  *().**      inte
24de0 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20  rfaces..** <li> 
24df0 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63  Run the SQL by c
24e00 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
24e10 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d  step()] one or m
24e20 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
24e30 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61  i> Reset the sta
24e40 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
24e50 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
24e60 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20  hen go back.**  
24e70 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20      to step 2.  
24e80 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20  Do this zero or 
24e90 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
24ea0 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20  li> Destroy the 
24eb0 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
24ec0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
24ed0 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  ]..** </ol>.**.*
24ee0 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d  * Refer to docum
24ef0 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  entation on indi
24f00 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61  vidual methods a
24f10 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f  bove for additio
24f20 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
24f30 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
24f40 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74  truct sqlite3_st
24f50 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b  mt sqlite3_stmt;
24f60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24f70 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74  : Run-time Limit
24f80 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  s.**.** ^(This i
24f90 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20  nterface allows 
24fa0 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69  the size of vari
24fb0 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74  ous constructs t
24fc0 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20  o be limited.** 
24fd0 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  on a connection 
24fe0 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  by connection ba
24ff0 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20  sis.  The first 
25000 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
25010 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
25020 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20  nnection] whose 
25030 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73  limit is to be s
25040 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20  et or queried.  
25050 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
25060 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f  rameter is one o
25070 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74  f the [limit cat
25080 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65  egories] that de
25090 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20  fine a.** class 
250a0 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  of constructs to
250b0 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64   be size limited
250c0 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72  .  The third par
250d0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
250e0 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74   new limit for t
250f0 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e  hat construct.)^
25100 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
25110 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65  ew limit is a ne
25120 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74  gative number, t
25130 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68  he limit is unch
25140 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20  anged..** ^(For 
25150 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67  each limit categ
25160 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ory SQLITE_LIMIT
25170 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65  _<i>NAME</i> the
25180 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
25190 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
251a0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61   bound].** set a
251b0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62  t compile-time b
251c0 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73  y a C preprocess
251d0 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a  or macro called.
251e0 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c  ** [limits | SQL
251f0 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c  ITE_MAX_<i>NAME<
25200 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  /i>]..** (The "_
25210 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
25220 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
25230 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a  o "_MAX_".))^.**
25240 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e   ^Attempts to in
25250 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
25260 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
25270 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
25280 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
25290 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
252a0 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a  upper bound..**.
252b0 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
252c0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
252d0 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63   the limit was c
252e0 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20  hanged, the .** 
252f0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
25300 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
25310 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61  rns the prior va
25320 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
25330 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20  ..** ^Hence, to 
25340 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74  find the current
25350 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69   value of a limi
25360 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69  t without changi
25370 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79  ng it,.** simply
25380 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74   invoke this int
25390 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20  erface with the 
253a0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
253b0 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a  set to -1..**.**
253c0 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73   Run-time limits
253d0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
253e0 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61  r use in applica
253f0 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67  tions that manag
25400 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20  e.** both their 
25410 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  own internal dat
25420 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64  abase and also d
25430 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72  atabases that ar
25440 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20  e controlled.** 
25450 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74  by untrusted ext
25460 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20  ernal sources.  
25470 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69  An example appli
25480 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  cation might be 
25490 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72  a.** web browser
254a0 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
254b0 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
254c0 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
254d0 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
254e0 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
254f0 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
25500 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
25510 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
25520 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
25530 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
25540 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
25550 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
25560 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
25570 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
25580 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
25590 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
255a0 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
255b0 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
255c0 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
255d0 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
255e0 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
255f0 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
25600 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
25610 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
25620 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
25630 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
25640 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
25650 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
25660 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
25670 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
25680 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
25690 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
256a0 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
256b0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
256c0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
256d0 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
256e0 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
256f0 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
25700 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
25710 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69  e releases..*/.i
25720 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
25730 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
25740 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
25750 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25760 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
25770 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
25780 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
25790 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
257a0 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
257b0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
257c0 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
257d0 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
257e0 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
257f0 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
25800 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
25810 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
25820 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
25830 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
25840 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
25850 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
25860 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
25870 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
25880 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
25890 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
258a0 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
258b0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
258c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
258d0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
258e0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
258f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
25900 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
25910 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
25920 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
25930 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
25940 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25950 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d  MIT_SQL_LENGTH]]
25960 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25970 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
25980 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
25990 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
259a0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
259b0 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
259c0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
259d0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d  TE_LIMIT_COLUMN]
259e0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
259f0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
25a00 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
25a10 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
25a20 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
25a30 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
25a40 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
25a50 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
25a60 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
25a70 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
25a80 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
25a90 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
25aa0 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
25ab0 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  clause.</dd>)^.*
25ac0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25ad0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d  MIT_EXPR_DEPTH]]
25ae0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25af0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
25b00 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
25b10 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
25b20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
25b30 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
25b40 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
25b50 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
25b60 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20  MPOUND_SELECT]] 
25b70 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
25b80 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
25b90 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
25ba0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
25bb0 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
25bc0 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
25bd0 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
25be0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
25bf0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d  _LIMIT_VDBE_OP]]
25c00 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25c10 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
25c20 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
25c30 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
25c40 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
25c50 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
25c60 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
25c70 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
25c80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
25c90 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f  This limit is no
25ca0 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65  t currently.** e
25cb0 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20  nforced, though 
25cc0 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64  that might be ad
25cd0 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ded in some futu
25ce0 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
25cf0 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a   SQLite.</dd>)^.
25d00 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
25d10 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
25d20 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  G]] ^(<dt>SQLITE
25d30 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
25d40 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
25d50 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
25d60 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
25d70 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
25d80 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
25d90 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
25da0 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  HED]] ^(<dt>SQLI
25db0 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
25dc0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
25dd0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
25de0 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
25df0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
25e00 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
25e10 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
25e20 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
25e30 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  TH]].** ^(<dt>SQ
25e40 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
25e50 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
25e60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
25e70 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
25e80 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
25e90 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
25ea0 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
25eb0 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
25ec0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
25ed0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
25ee0 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c  _NUMBER]].** ^(<
25ef0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
25f00 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
25f10 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
25f20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
25f30 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
25f40 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
25f50 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
25f60 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25f70 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
25f80 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
25f90 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
25fa0 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
25fb0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
25fc0 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
25fd0 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
25fe0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
25ff0 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
26000 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74  _THREADS]] ^(<dt
26010 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f  >SQLITE_LIMIT_WO
26020 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74  RKER_THREADS</dt
26030 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
26040 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
26050 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20  uxiliary worker 
26060 74 68 72 65 61 64 73 20 74 68 61 74 20 61 20 73  threads that a s
26070 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72  ingle.** [prepar
26080 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61  ed statement] ma
26090 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a  y start.</dd>)^.
260a0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
260b0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
260c0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
260d0 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
260e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
260f0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
26100 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
26110 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
26120 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
26130 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
26140 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
26150 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
26160 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
26170 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
26180 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
26190 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
261a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
261b0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
261c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
261d0 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
261e0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
261f0 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
26200 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
26210 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
26220 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26230 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
26240 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
26250 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
26260 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
26270 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
26280 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
26290 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
262a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
262b0 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  ER_DEPTH        
262c0 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
262d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
262e0 45 52 5f 54 48 52 45 41 44 53 20 20 20 20 20 20  ER_THREADS      
262f0 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43       11../*.** C
26300 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
26310 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
26320 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ent.** KEYWORDS:
26330 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   {SQL statement 
26340 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20  compiler}.**.** 
26350 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
26360 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
26370 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
26380 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
26390 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
263a0 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
263b0 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
263c0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
263d0 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61  ment, "db", is a
263e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
263f0 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20  ction] obtained 
26400 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20  from a.** prior 
26410 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
26420 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
26430 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
26440 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b  en_v2()] or.** [
26450 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
26460 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65  ].  The database
26470 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
26480 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63   not have been c
26490 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
264a0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
264b0 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65  , "zSql", is the
264c0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
264d0 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64   compiled, encod
264e0 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20  ed.** as either 
264f0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e  UTF-8 or UTF-16.
26500 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72    The sqlite3_pr
26510 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69  epare() and sqli
26520 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
26530 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
26540 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
26550 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
26560 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
26570 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20  epare16_v2().** 
26580 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
26590 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20  * ^If the nByte 
265a0 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73  argument is less
265b0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e   than zero, then
265c0 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
265d0 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
265e0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
265f0 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e  . ^If nByte is n
26600 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
26610 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69  n it is the maxi
26620 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  mum.** number of
26630 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f    bytes read fro
26640 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e  m zSql.  ^When n
26650 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
26660 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71  tive, the.** zSq
26670 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74  l string ends at
26680 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73   either the firs
26690 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30  t '\000' or '\u0
266a0 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f  000' character o
266b0 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74  r.** the nByte-t
266c0 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65  h byte, whicheve
266d0 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49  r comes first. I
266e0 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
266f0 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73  ws.** that the s
26700 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69  upplied string i
26710 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  s nul-terminated
26720 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  , then there is 
26730 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f  a small.** perfo
26740 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65  rmance advantage
26750 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79   to be gained by
26760 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
26770 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
26780 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20  .** is equal to 
26790 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
267a0 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
267b0 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
267c0 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
267d0 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62  nul-terminator b
267e0 79 74 65 73 20 61 73 20 74 68 69 73 20 73 61 76  ytes as this sav
267f0 65 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 68  es SQLite from h
26800 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65  aving to.** make
26810 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 69   a copy of the i
26820 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  nput string..**.
26830 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
26840 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
26850 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
26860 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
26870 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
26880 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
26890 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
268a0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
268b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
268c0 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
268d0 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
268e0 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
268f0 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
26900 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
26910 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
26920 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
26930 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
26940 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
26950 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
26960 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
26970 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
26980 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
26990 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
269a0 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
269b0 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
269c0 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
269d0 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
269e0 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
269f0 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
26a00 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
26a10 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
26a20 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
26a30 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
26a40 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
26a50 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
26a60 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
26a70 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
26a80 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
26a90 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
26aa0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
26ab0 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
26ac0 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
26ad0 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
26ae0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
26af0 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
26b00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
26b10 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
26b20 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
26b30 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
26b40 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
26b50 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
26b60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
26b70 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
26b80 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
26b90 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
26ba0 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
26bb0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
26bc0 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
26bd0 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
26be0 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
26bf0 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
26c00 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
26c10 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
26c20 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
26c30 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76  d..** ^In the "v
26c40 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
26c50 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
26c60 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
26c70 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
26c80 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
26c90 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
26ca0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
26cb0 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
26cc0 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
26cd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
26ce0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
26cf0 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65  .** behave diffe
26d00 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20  rently in three 
26d10 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
26d20 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
26d30 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
26d40 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
26d50 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
26d60 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
26d70 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
26d80 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
26d90 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
26da0 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
26db0 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
26dc0 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
26dd0 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
26de0 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e  it again. As man
26df0 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58  y as [SQLITE_MAX
26e00 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a  _SCHEMA_RETRY].*
26e10 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f  * retries will o
26e20 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69  ccur before sqli
26e30 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73  te3_step() gives
26e40 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20   up and returns 
26e50 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c  an error..** </l
26e60 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
26e70 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
26e80 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
26e90 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
26ea0 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
26eb0 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
26ec0 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
26ed0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
26ee0 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
26ef0 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
26f00 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
26f10 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
26f20 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
26f30 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
26f40 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
26f50 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
26f60 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
26f70 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
26f80 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
26f90 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
26fa0 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
26fb0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
26fc0 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
26fd0 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
26fe0 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
26ff0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
27000 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
27010 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
27020 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
27030 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
27040 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
27050 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76  f the specific v
27060 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70  alue bound to [p
27070 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20  arameter | host 
27080 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
27090 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  e .** WHERE clau
270a0 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  se might influen
270b0 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66  ce the choice of
270c0 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20   query plan for 
270d0 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20  a statement,.** 
270e0 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  then the stateme
270f0 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  nt will be autom
27100 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
27110 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65  led, as if there
27120 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20   had been .** a 
27130 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f  schema change, o
27140 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71  n the first  [sq
27150 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
27160 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ll following any
27170 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68   change.** to th
27180 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
27190 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d  text | bindings]
271a0 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65   of that [parame
271b0 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73  ter]. .** ^The s
271c0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66  pecific value of
271d0 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70   WHERE-clause [p
271e0 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20  arameter] might 
271f0 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a  influence the .*
27200 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  * choice of quer
27210 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61  y plan if the pa
27220 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c  rameter is the l
27230 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
27240 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20   a [LIKE].** or 
27250 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20  [GLOB] operator 
27260 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  or if the parame
27270 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20  ter is compared 
27280 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f  to an indexed co
27290 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20  lumn.** and the 
272a0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
272b0 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  TAT3] compile-ti
272c0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
272d0 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  bled..** </li>.*
272e0 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ol>.*/.int s
272f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
27300 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
27310 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
27320 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
27330 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
27340 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
27350 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
27360 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
27370 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
27380 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
27390 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
273a0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
273b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
273c0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
273d0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
273e0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
273f0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
27400 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
27410 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
27420 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
27430 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
27440 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
27450 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
27460 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
27470 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
27480 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
27490 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
274a0 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
274b0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
274c0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
274d0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
274e0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
274f0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
27500 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
27510 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
27520 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
27530 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
27540 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
27550 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
27560 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
27570 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
27580 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
27590 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
275a0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
275b0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
275c0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
275d0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
275e0 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
275f0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
27600 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
27610 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
27620 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
27630 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
27640 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
27650 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
27660 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
27670 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
27680 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
27690 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
276a0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
276b0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
276c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
276d0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
276e0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
276f0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
27700 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
27710 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
27720 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
27730 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
27740 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
27750 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
27760 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
27770 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
27780 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
27790 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
277a0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
277b0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
277c0 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
277d0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
277e0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
277f0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
27800 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27810 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53  EF: Retrieving S
27820 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a  tatement SQL.**.
27830 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
27840 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
27850 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76  o retrieve a sav
27860 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f  ed copy of the o
27870 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74  riginal.** SQL t
27880 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
27890 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
278a0 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61  tatement] if tha
278b0 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a  t statement was.
278c0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e  ** compiled usin
278d0 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
278e0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
278f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
27900 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  are16_v2()]..*/.
27910 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
27920 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  te3_sql(sqlite3_
27930 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
27940 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
27950 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
27960 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69  QL Statement Wri
27970 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65  tes The Database
27980 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
27990 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
279a0 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(X) interface r
279b0 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
279c0 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64  -zero) if.** and
279d0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72   only if the [pr
279e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
279f0 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72  ] X makes no dir
27a00 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
27a10 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
27a20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
27a30 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  le..**.** Note t
27a40 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  hat [application
27a50 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
27a60 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76  ctions] or.** [v
27a70 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d  irtual tables] m
27a80 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20  ight change the 
27a90 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63  database indirec
27aa0 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66  tly as a side ef
27ab0 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72  fect.  .** ^(For
27ac0 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20   example, if an 
27ad0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
27ae0 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22  nes a function "
27af0 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a  eval()" that .**
27b00 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f   calls [sqlite3_
27b10 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68  exec()], then th
27b20 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20  e following SQL 
27b30 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a  statement would.
27b40 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ** change the da
27b50 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f  tabase file thro
27b60 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73  ugh side-effects
27b70 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
27b80 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
27b90 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c  SELECT eval('DEL
27ba0 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52  ETE FROM t1') FR
27bb0 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  OM t2;.** </pre>
27bc0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
27bd0 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20  .** But because 
27be0 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
27bf0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
27c00 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
27c10 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65  ase file.** dire
27c20 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74  ctly, sqlite3_st
27c30 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f  mt_readonly() wo
27c40 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e  uld still return
27c50 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   true.)^.**.** ^
27c60 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  Transaction cont
27c70 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73  rol statements s
27c80 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20  uch as [BEGIN], 
27c90 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42  [COMMIT], [ROLLB
27ca0 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f  ACK],.** [SAVEPO
27cb0 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41  INT], and [RELEA
27cc0 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65  SE] cause sqlite
27cd0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
27ce0 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
27cf0 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73  ,.** since the s
27d00 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65  tatements themse
27d10 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75  lves do not actu
27d20 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  ally modify the 
27d30 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20  database but.** 
27d40 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74  rather they cont
27d50 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f  rol the timing o
27d60 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61  f when other sta
27d70 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74  tements modify t
27d80 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  he .** database.
27d90 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20    ^The [ATTACH] 
27da0 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61  and [DETACH] sta
27db0 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75  tements also cau
27dc0 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  se.** sqlite3_st
27dd0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
27de0 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e   return true sin
27df0 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20  ce, while those 
27e00 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68  statements.** ch
27e10 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75  ange the configu
27e20 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61  ration of a data
27e30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
27e40 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b   they do not mak
27e50 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  e .** changes to
27e60 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
27e70 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
27e80 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69  es on disk..*/.i
27e90 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
27ea0 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
27eb0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
27ec0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27ed0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50  Determine If A P
27ee0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
27ef0 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74  t Has Been Reset
27f00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
27f10 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
27f20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
27f30 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
27f40 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72  o) if the.** [pr
27f50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27f60 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65  ] S has been ste
27f70 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e  pped at least on
27f80 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  ce using .** [sq
27f90 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62  lite3_step(S)] b
27fa0 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74  ut has not run t
27fb0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64  o completion and
27fc0 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20  /or has not .** 
27fd0 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67  been reset using
27fe0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
27ff0 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  S)].  ^The sqlit
28000 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a  e3_stmt_busy(S).
28010 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
28020 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20  urns false if S 
28030 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
28040 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20  r.  If S is not 
28050 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74  a .** NULL point
28060 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  er and is not a 
28070 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
28080 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  id [prepared sta
28090 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
280a0 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  t, then the beha
280b0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
280c0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
280d0 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a  ndesirable..**.*
280e0 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
280f0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20   can be used in 
28100 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c  combination [sql
28110 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29  ite3_next_stmt()
28120 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61  ].** to locate a
28130 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ll prepared stat
28140 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65  ements associate
28150 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  d with a databas
28160 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  e .** connection
28170 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65   that are in nee
28180 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74  d of being reset
28190 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75  .  This can be u
281a0 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d  sed,.** for exam
281b0 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74  ple, in diagnost
281c0 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73  ic routines to s
281d0 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72  earch for prepar
281e0 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ed .** statement
281f0 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69  s that are holdi
28200 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
28210 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71   open..*/.int sq
28220 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
28230 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
28240 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28250 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
28260 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
28270 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
28280 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
28290 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
282a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
282b0 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
282c0 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
282d0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
282e0 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
282f0 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
28300 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
28310 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
28320 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
28330 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
28340 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
28350 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
28360 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
28370 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
28380 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
28390 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
283a0 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
283b0 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
283c0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
283d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
283e0 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
283f0 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
28400 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
28410 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
28420 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
28430 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
28440 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
28450 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
28460 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
28470 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
28480 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
28490 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
284a0 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
284b0 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
284c0 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
284d0 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
284e0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
284f0 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
28500 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
28510 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
28520 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
28530 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
28540 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
28550 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
28560 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
28570 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74   An internal mut
28580 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
28590 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71   protected.** sq
285a0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
285b0 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20  ct but no mutex 
285c0 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75  is held for an u
285d0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
285e0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
285f0 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ct.  If SQLite i
28600 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65  s compiled to be
28610 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
28620 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54  .** (with [SQLIT
28630 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
28640 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
28650 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
28660 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
28670 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  or if SQLite is 
28680 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65  run in one of re
28690 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65  duced mutex mode
286a0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  s .** [SQLITE_CO
286b0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
286c0 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  D] or [SQLITE_CO
286d0 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
286e0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ].** then there 
286f0 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
28700 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
28710 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
28720 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
28730 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
28740 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65   they can be use
28750 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
28760 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  y.  However,.** 
28770 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
28780 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20   portability it 
28790 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
287a0 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
287b0 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74  .** still make t
287c0 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  he distinction b
287d0 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
287e0 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
287f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
28800 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
28810 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
28820 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
28830 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
28840 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74  lue objects that
28850 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70   are passed as p
28860 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74  arameters into t
28870 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
28880 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61  tion of [applica
28890 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
288a0 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20   functions] are 
288b0 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54  protected..** ^T
288c0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
288d0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
288e0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
288f0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
28900 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a  is unprotected..
28910 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73  ** Unprotected s
28920 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
28930 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ects may only be
28940 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73   used with.** [s
28950 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
28960 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
28970 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
28980 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
28990 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20  e3_value_blob | 
289a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
289b0 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  pe()] family of.
289c0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  ** interfaces re
289d0 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20  quire protected 
289e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
289f0 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  jects..*/.typede
28a00 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c  f struct Mem sql
28a10 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
28a20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
28a30 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
28a40 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
28a50 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
28a60 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
28a70 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
28a80 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
28a90 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
28aa0 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e  object.  ^A poin
28ab0 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
28ac0 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
28ad0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
28ae0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
28af0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
28b00 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
28b10 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
28b20 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
28b30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
28b40 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
28b50 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
28b60 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
28b70 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
28b80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
28b90 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
28ba0 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
28bb0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
28bc0 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
28bd0 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
28be0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
28bf0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
28c00 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
28c10 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
28c20 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
28c30 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
28c40 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
28c50 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
28c60 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
28c70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28c80 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
28c90 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
28ca0 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52  ements.** KEYWOR
28cb0 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  DS: {host parame
28cc0 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ter} {host param
28cd0 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72  eters} {host par
28ce0 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20  ameter name}.** 
28cf0 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70  KEYWORDS: {SQL p
28d00 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70  arameter} {SQL p
28d10 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61  arameters} {para
28d20 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a  meter binding}.*
28d30 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
28d40 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
28d50 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
28d60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
28d70 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
28d80 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
28d90 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
28da0 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
28db0 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
28dc0 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
28dd0 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
28de0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
28df0 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
28e00 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
28e10 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
28e20 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
28e30 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
28e40 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
28e50 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
28e60 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
28e70 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
28e80 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
28e90 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
28ea0 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
28eb0 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
28ec0 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
28ed0 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
28ee0 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
28ef0 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
28f00 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
28f10 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
28f20 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
28f30 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
28f40 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
28f50 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
28f60 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
28f70 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
28f80 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
28f90 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
28fa0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
28fb0 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
28fc0 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
28fd0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
28fe0 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
28ff0 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
29000 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
29010 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
29020 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
29030 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
29040 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
29050 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
29060 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
29070 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
29080 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
29090 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
290a0 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
290b0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
290c0 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
290d0 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
290e0 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
290f0 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
29100 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
29110 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
29120 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
29130 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
29140 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
29150 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
29160 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
29170 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
29180 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
29190 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
291a0 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
291b0 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
291c0 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
291d0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
291e0 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
291f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
29200 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
29210 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
29220 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
29230 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
29240 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
29250 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
29260 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
29270 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
29280 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
29290 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
292a0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
292b0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
292c0 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e  nd_blob() is a N
292d0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
292e0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
292f0 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f  meter.** is igno
29300 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20  red and the end 
29310 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61  result is the sa
29320 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69  me as sqlite3_bi
29330 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a  nd_null()..**.**
29340 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74   ^(In those rout
29350 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
29360 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
29370 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
29380 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
29390 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
293a0 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
293b0 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
293c0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
293d0 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
293e0 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
293f0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
29400 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a   characters.)^.*
29410 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68  * ^If the fourth
29420 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
29430 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
29440 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
29450 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73  d_text16().** is
29460 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
29470 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
29480 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
29490 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
294a0 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
294b0 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
294c0 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f  or..** If the fo
294d0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
294e0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
294f0 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76  lob() is negativ
29500 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62  e, then.** the b
29510 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
29520 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f  ined..** If a no
29530 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74  n-negative fourt
29540 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  h parameter is p
29550 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74  rovided to sqlit
29560 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a  e3_bind_text().*
29570 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
29580 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71  d_text16() or sq
29590 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
295a0 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74  4() then.** that
295b0 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
295c0 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
295d0 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20  et.** where the 
295e0 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
295f0 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d  ould occur assum
29600 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77  ing the string w
29610 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69  ere NUL.** termi
29620 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
29630 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
29640 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73  cur at byte offs
29650 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a  ets less than .*
29660 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * the value of t
29670 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
29680 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73  ter then the res
29690 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61  ulting string va
296a0 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  lue will.** cont
296b0 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
296c0 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f  s.  The result o
296d0 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  f expressions in
296e0 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a  volving strings.
296f0 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  ** with embedded
29700 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
29710 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
29720 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
29730 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74   the BLOB and st
29740 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74  ring binding int
29750 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20  erfaces.** is a 
29760 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
29770 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
29780 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
29790 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
297a0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
297b0 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
297c0 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
297d0 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
297e0 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
297f0 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
29800 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41  e call to bind A
29810 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66  PI fails..** ^If
29820 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
29830 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
29840 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
29850 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
29860 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
29870 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
29880 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
29890 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
298a0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
298b0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
298c0 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
298d0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
298e0 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
298f0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
29900 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
29910 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
29920 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
29930 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
29940 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
29950 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
29960 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
29970 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
29980 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
29990 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
299a0 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20  ext64() must be 
299b0 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54  one of.** [SQLIT
299c0 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
299d0 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45  _UTF16], [SQLITE
299e0 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53  _UTF16BE], or [S
299f0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a  QLITE_UTF16LE].*
29a00 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  * to specify the
29a10 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65   encoding of the
29a20 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69   text in the thi
29a30 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  rd parameter.  I
29a40 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61  f.** the sixth a
29a50 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
29a60 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
29a70 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
29a80 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61  he.** allowed va
29a90 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  lues shown above
29aa0 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74  , or if the text
29ab0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
29ac0 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74  ferent.** from t
29ad0 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
29ae0 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78  ified by the six
29af0 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  th parameter, th
29b00 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
29b10 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
29b20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29b30 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
29b40 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
29b50 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
29b60 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
29b70 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
29b80 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
29b90 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
29ba0 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
29bb0 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
29bc0 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
29bd0 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
29be0 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
29bf0 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
29c00 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
29c10 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
29c20 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
29c30 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
29c40 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
29c50 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
29c60 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
29c70 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
29c80 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
29c90 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
29ca0 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
29cb0 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
29cc0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
29cd0 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  OB..**.** ^If an
29ce0 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  y of the sqlite3
29cf0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
29d00 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69  es are called wi
29d10 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
29d20 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72  r.** for the [pr
29d30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29d40 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70  ] or with a prep
29d50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66  ared statement f
29d60 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  or which.** [sql
29d70 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
29d80 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72   been called mor
29d90 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20  e recently than 
29da0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
29db0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  ],.** then the c
29dc0 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  all will return 
29dd0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
29de0 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33    If any sqlite3
29df0 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74  _bind_().** rout
29e00 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20  ine is passed a 
29e10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29e20 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65  ent] that has be
29e30 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68  en finalized, th
29e40 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75  e.** result is u
29e50 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
29e60 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  bably harmful..*
29e70 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61  *.** ^Bindings a
29e80 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
29e90 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
29ea0 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
29eb0 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72  .** ^Unbound par
29ec0 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
29ed0 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
29ee0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29ef0 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69  te3_bind_* routi
29f00 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
29f10 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
29f20 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  s or an.** [erro
29f30 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68  r code] if anyth
29f40 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
29f50 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42  ** ^[SQLITE_TOOB
29f60 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  IG] might be ret
29f70 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a  urned if the siz
29f80 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72  e of a string or
29f90 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73   BLOB.** exceeds
29fa0 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20   limits imposed 
29fb0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
29fc0 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
29fd0 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20  _LENGTH]) or.** 
29fe0 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47  [SQLITE_MAX_LENG
29ff0 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  TH]..** ^[SQLITE
2a000 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
2a010 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
2a020 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
2a030 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
2a040 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
2a050 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
2a060 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
2a070 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2a080 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2a090 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2a0a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2a0b0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2a0c0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
2a0d0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2a0e0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
2a0f0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
2a100 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2a110 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
2a120 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
2a130 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2a140 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2a150 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  ob64(sqlite3_stm
2a160 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
2a170 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  oid*, sqlite3_ui
2a180 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
2a190 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
2a1a0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
2a1b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2a1c0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
2a1d0 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
2a1e0 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
2a1f0 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
2a200 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
2a210 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2a220 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
2a230 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
2a240 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e  lite3_int64);.in
2a250 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  t sqlite3_bind_n
2a260 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
2a270 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  *, int);.int sql
2a280 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
2a290 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2a2a0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74  ,const char*,int
2a2b0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
2a2c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2a2d0 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
2a2e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2a2f0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
2a300 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2a310 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2a320 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33  d_text64(sqlite3
2a330 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2a340 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
2a350 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20  3_uint64,.      
2a360 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a370 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
2a380 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  ), unsigned char
2a390 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20   encoding);.int 
2a3a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
2a3b0 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
2a3c0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c  , int, const sql
2a3d0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2a3e0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
2a3f0 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
2a400 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
2a410 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
2a420 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
2a430 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  QL Parameters.**
2a440 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
2a450 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
2a460 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
2a470 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74   of [SQL paramet
2a480 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72  ers].** in a [pr
2a490 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a4a0 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ].  SQL paramete
2a4b0 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66  rs are tokens of
2a4c0 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22   the.** form "?"
2a4d0 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22  , "?NNN", ":AAA"
2a4e0 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41  , "$AAA", or "@A
2a4f0 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61  AA" that serve a
2a500 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72  s.** placeholder
2a510 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61  s for values tha
2a520 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62  t are [sqlite3_b
2a530 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64  ind_blob | bound
2a540 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61  ].** to the para
2a550 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65  meters at a late
2a560 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  r time..**.** ^(
2a570 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74  This routine act
2a580 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
2a590 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c  e index of the l
2a5a0 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73  argest (rightmos
2a5b0 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  t).** parameter.
2a5c0 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
2a5d0 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
2a5e0 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
2a5f0 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   to the.** numbe
2a600 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61  r of unique para
2a610 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
2a620 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
2a630 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64  NN form are used
2a640 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62  ,.** there may b
2a650 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
2a660 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  st.)^.**.** See 
2a670 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2a680 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2a690 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2a6a0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2a6b0 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
2a6c0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2a6d0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2a6e0 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
2a6f0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2a700 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
2a710 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2a720 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
2a730 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
2a740 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eter.**.** ^The 
2a750 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2a760 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29  ameter_name(P,N)
2a770 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2a780 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ns.** the name o
2a790 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20  f the N-th [SQL 
2a7a0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
2a7b0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2a7c0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53  ement] P..** ^(S
2a7d0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  QL parameters of
2a7e0 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
2a7f0 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
2a800 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
2a810 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68  * have a name wh
2a820 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
2a830 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  g "?NNN" or ":AA
2a840 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
2a850 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63  "$AAA".** respec
2a860 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74  tively..** In ot
2a870 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
2a880 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
2a890 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a  " or "@" or "?".
2a8a0 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
2a8b0 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
2a8c0 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65  me.)^.** ^Parame
2a8d0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
2a8e0 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
2a8f0 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
2a900 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
2a910 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65   and are referre
2a920 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73  d to as "nameles
2a930 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73  s" or "anonymous
2a940 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
2a950 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68  .** ^The first h
2a960 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
2a970 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
2a980 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49   not 0..**.** ^I
2a990 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73  f the value N is
2a9a0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
2a9b0 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72   if the N-th par
2a9c0 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
2a9d0 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
2a9e0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   is returned.  ^
2a9f0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2aa00 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
2aa10 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
2aa20 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
2aa30 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
2aa40 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
2aa50 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
2aa60 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
2aa70 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
2aa80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2aa90 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
2aaa0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2aab0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2aac0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2aad0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2aae0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2aaf0 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
2ab00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2ab10 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2ab20 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2ab30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2ab40 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74  meter_name(sqlit
2ab50 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
2ab60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ab70 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61   Index Of A Para
2ab80 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76  meter With A Giv
2ab90 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52  en Name.**.** ^R
2aba0 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
2abb0 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
2abc0 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
2abd0 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64  me.  ^The.** ind
2abe0 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
2abf0 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
2ac00 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
2ac10 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
2ac20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
2ac30 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2ac40 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f  ind()].  ^A zero
2ac50 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
2ac60 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70  if no matching p
2ac70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e  arameter is foun
2ac80 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  d.  ^The paramet
2ac90 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
2aca0 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
2acb0 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
2acc0 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
2acd0 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
2ace0 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
2acf0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
2ad00 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2ad10 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2ad20 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2ad30 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2ad40 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2ad50 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2ad60 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
2ad70 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2ad80 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2ad90 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
2ada0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2adb0 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
2adc0 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
2add0 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
2ade0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2adf0 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
2ae00 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
2ae10 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f  tement.**.** ^Co
2ae20 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e  ntrary to the in
2ae30 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c  tuition of many,
2ae40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2ae50 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65  )] does not rese
2ae60 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  t.** the [sqlite
2ae70 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69  3_bind_blob | bi
2ae80 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72  ndings] on a [pr
2ae90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2aea0 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20  ]..** ^Use this 
2aeb0 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74  routine to reset
2aec0 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
2aed0 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  ters to NULL..*/
2aee0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65  .int sqlite3_cle
2aef0 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
2af00 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2af10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2af20 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
2af30 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
2af40 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
2af50 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2af60 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
2af70 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
2af80 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2af90 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54  d statement]. ^T
2afa0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
2afb0 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69  rns 0 if pStmt i
2afc0 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74  s an SQL.** stat
2afd0 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20  ement that does 
2afe0 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20  not return data 
2aff0 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
2b000 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a  [UPDATE])..**.**
2b010 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2b020 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
2b030 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
2b040 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
2b050 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2b060 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2b070 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
2b080 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
2b090 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
2b0a0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2b0b0 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
2b0c0 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
2b0d0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
2b0e0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
2b0f0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
2b100 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69  ment.  ^The sqli
2b110 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2b120 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
2b130 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2b140 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
2b150 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
2b160 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
2b170 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2b180 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
2b190 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
2b1a0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
2b1b0 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
2b1c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2b1d0 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65   is the [prepare
2b1e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2b1f0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
2b200 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
2b210 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63  tement. ^The sec
2b220 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
2b230 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
2b240 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66  umber.  ^The lef
2b250 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  tmost column is 
2b260 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20  number 0..**.** 
2b270 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2b280 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
2b290 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
2b2a0 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
2b2b0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
2b2c0 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
2b2d0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2b2e0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
2b2f0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
2b300 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
2b310 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
2b320 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
2b330 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2b340 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2b350 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
2b360 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74   the next call t
2b370 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
2b380 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71  umn_name() or sq
2b390 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2b3a0 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d  e16() on the sam
2b3b0 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  e column..**.** 
2b3c0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
2b3d0 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
2b3e0 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
2b3f0 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
2b400 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
2b410 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
2b420 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
2b430 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
2b440 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
2b450 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
2b460 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2b470 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c   of a result col
2b480 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65  umn is the value
2b490 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61   of the "AS" cla
2b4a0 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20  use for.** that 
2b4b0 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65  column, if there
2b4c0 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65   is an AS clause
2b4d0 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
2b4e0 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74  o AS clause.** t
2b4f0 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  hen the name of 
2b500 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e  the column is un
2b510 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61  specified and ma
2b520 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a  y change from.**
2b530 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20   one release of 
2b540 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65  SQLite to the ne
2b550 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  xt..*/.const cha
2b560 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2b570 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2b580 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f  tmt*, int N);.co
2b590 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2b5a0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2b5b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b5c0 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
2b5d0 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
2b5e0 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
2b5f0 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
2b600 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
2b610 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
2b620 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
2b630 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2b640 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
2b650 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
2b660 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
2b670 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
2b680 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
2b690 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
2b6a0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2b6b0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
2b6c0 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
2b6d0 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
2b6e0 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
2b6f0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
2b700 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
2b710 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
2b720 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
2b730 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
2b740 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
2b750 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
2b760 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
2b770 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
2b780 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2b790 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
2b7a0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2b7b0 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
2b7c0 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
2b7d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
2b7e0 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
2b7f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
2b800 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2b810 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2b820 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2b830 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2b840 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2b850 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2b860 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2b870 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2b880 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
2b890 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
2b8a0 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
2b8b0 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
2b8c0 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
2b8d0 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
2b8e0 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
2b8f0 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
2b900 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
2b910 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2b920 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
2b930 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2b940 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
2b950 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
2b960 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b970 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
2b980 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2b990 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2b9a0 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
2b9b0 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
2b9c0 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
2b9d0 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
2b9e0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
2b9f0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
2ba00 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
2ba10 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
2ba20 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
2ba30 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
2ba40 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
2ba50 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
2ba60 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2ba70 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
2ba80 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
2ba90 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
2baa0 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
2bab0 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2bac0 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
2bad0 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
2bae0 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
2baf0 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
2bb00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2bb10 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
2bb20 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
2bb30 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
2bb40 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
2bb50 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
2bb60 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
2bb70 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
2bb80 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
2bb90 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
2bba0 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
2bbb0 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
2bbc0 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
2bbd0 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
2bbe0 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
2bbf0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
2bc00 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
2bc10 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
2bc20 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
2bc30 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
2bc40 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
2bc50 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
2bc60 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
2bc70 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
2bc80 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
2bc90 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
2bca0 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
2bcb0 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
2bcc0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
2bcd0 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
2bce0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2bcf0 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
2bd00 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
2bd10 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
2bd20 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
2bd30 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
2bd40 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
2bd50 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
2bd60 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2bd70 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2bd80 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
2bd90 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2bda0 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
2bdb0 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
2bdc0 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
2bdd0 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
2bde0 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
2bdf0 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
2be00 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2be10 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2be20 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
2be30 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2be40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2be50 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
2be60 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2be70 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2be80 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2be90 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
2bea0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2beb0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2bec0 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
2bed0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2bee0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2bef0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2bf00 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
2bf10 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2bf20 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
2bf30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
2bf40 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
2bf50 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2bf60 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2bf70 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
2bf80 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2bf90 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
2bfa0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
2bfb0 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
2bfc0 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
2bfd0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73  **.** ^(The firs
2bfe0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
2bff0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c000 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69  ment]..** If thi
2c010 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  s statement is a
2c020 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2c030 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20  ent and the Nth 
2c040 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
2c050 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74   returned result
2c060 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45   set of that [SE
2c070 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65  LECT] is a table
2c080 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a   column (not an.
2c090 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
2c0a0 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20   subquery) then 
2c0b0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
2c0c0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
2c0d0 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75  * column is retu
2c0e0 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65  rned.)^  ^If the
2c0f0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
2c100 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73  he result set is
2c110 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
2c120 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74  n or subquery, t
2c130 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  hen a NULL point
2c140 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
2c150 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
2c160 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
2c170 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
2c180 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .**.** ^(For exa
2c190 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20  mple, given the 
2c1a0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
2c1b0 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
2c1c0 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
2c1d0 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68  T);.**.** and th
2c1e0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
2c1f0 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
2c200 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45  iled:.**.** SELE
2c210 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52  CT c1 + 1, c1 FR
2c220 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69  OM t1;.**.** thi
2c230 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20  s routine would 
2c240 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e  return the strin
2c250 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20  g "VARIANT" for 
2c260 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c  the second resul
2c270 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  t.** column (i==
2c280 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70  1), and a NULL p
2c290 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66  ointer for the f
2c2a0 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75  irst result colu
2c2b0 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a  mn (i==0).)^.**.
2c2c0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
2c2d0 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65  dynamic run-time
2c2e0 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75   typing.  ^So ju
2c2f0 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
2c300 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
2c310 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
2c320 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
2c330 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
2c340 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
2c350 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
2c360 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
2c370 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
2c380 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
2c390 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
2c3a0 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
2c3b0 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
2c3c0 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61  .  ^Type.** is a
2c3d0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69  ssociated with i
2c3e0 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73  ndividual values
2c3f0 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63  , not with the c
2c400 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65  ontainers.** use
2c410 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20  d to hold those 
2c420 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  values..*/.const
2c430 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2c440 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
2c450 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2c460 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2c470 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
2c480 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
2c490 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
2c4a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
2c4b0 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
2c4c0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66  atement.**.** Af
2c4d0 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
2c4e0 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
2c4f0 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
2c500 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  ng either.** [sq
2c510 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2c520 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2c530 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2c540 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65  or one of the le
2c550 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2c560 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
2c570 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
2c580 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
2c590 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
2c5a0 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  * must be called
2c5b0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
2c5c0 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  es to evaluate t
2c5d0 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  he statement..**
2c5e0 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
2c5f0 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
2c600 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  of the sqlite3_s
2c610 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
2c620 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
2c630 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
2c640 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
2c650 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
2c660 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a  "v2" interface.*
2c670 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2c680 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
2c690 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2c6a0 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
2c6b0 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
2c6c0 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f  erface [sqlite3_
2c6d0 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
2c6e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2c6f0 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
2c700 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32  f the.** new "v2
2c710 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
2c720 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
2c730 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
2c740 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
2c750 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
2c760 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
2c770 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
2c780 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20   ^In the legacy 
2c790 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
2c7a0 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
2c7b0 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
2c7c0 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
2c7d0 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
2c7e0 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
2c7f0 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
2c800 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
2c810 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20   ^With the "v2" 
2c820 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
2c830 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73  f the other [res
2c840 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a  ult codes] or.**
2c850 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
2c860 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62  t codes] might b
2c870 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65  e returned as we
2c880 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ll..**.** ^[SQLI
2c890 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
2c8a0 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
2c8b0 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
2c8c0 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
2c8d0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
2c8e0 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
2c8f0 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66  do its job.  ^If
2c900 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2c910 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
2c920 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
2c930 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
2c940 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
2c950 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
2c960 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
2c970 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
2c980 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
2c990 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
2c9a0 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65  s within an.** e
2c9b0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
2c9c0 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
2c9d0 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
2c9e0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
2c9f0 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
2ca00 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  g..**.** ^[SQLIT
2ca10 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
2ca20 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
2ca30 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
2ca40 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
2ca50 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
2ca60 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
2ca70 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
2ca80 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
2ca90 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
2caa0 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
2cab0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2cac0 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
2cad0 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
2cae0 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
2caf0 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
2cb00 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2cb10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65  SQL statement be
2cb20 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74  ing executed ret
2cb30 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74  urns any data, t
2cb40 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  hen [SQLITE_ROW]
2cb50 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
2cb60 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20  each time a new 
2cb70 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72  row of data is r
2cb80 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73  eady for process
2cb90 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  ing by the.** ca
2cba0 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73  ller. The values
2cbb0 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
2cbc0 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75   using the [colu
2cbd0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2cbe0 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  ons]..** sqlite3
2cbf0 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65  _step() is calle
2cc00 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69  d again to retri
2cc10 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77  eve the next row
2cc20 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
2cc30 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20  ^[SQLITE_ERROR] 
2cc40 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
2cc50 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
2cc60 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
2cc70 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
2cc80 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
2cc90 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
2cca0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
2ccb0 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
2ccc0 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
2ccd0 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
2cce0 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
2ccf0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
2cd00 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  )]..** ^With the
2cd10 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2cd20 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
2cd30 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66  ic error code (f
2cd40 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b  or example,.** [
2cd50 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
2cd60 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ], [SQLITE_SCHEM
2cd70 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  A], [SQLITE_CORR
2cd80 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72  UPT], and so for
2cd90 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62  th).** can be ob
2cda0 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  tained by callin
2cdb0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2cdc0 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70  ()] on the.** [p
2cdd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cde0 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32  t].  ^In the "v2
2cdf0 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
2ce00 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
2ce10 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
2ce20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
2ce30 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
2ce40 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
2ce50 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
2ce60 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
2ce70 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
2ce80 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
2ce90 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
2cea0 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
2ceb0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2cec0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
2ced0 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
2cee0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2cef0 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
2cf00 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
2cf10 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72  .** previously r
2cf20 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2cf30 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54  ERROR] or [SQLIT
2cf40 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20  E_DONE].  Or it 
2cf50 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20  could.** be the 
2cf60 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61  case that the sa
2cf70 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
2cf80 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  ection is being 
2cf90 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a  used by two or.*
2cfa0 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61  * more threads a
2cfb0 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e  t the same momen
2cfc0 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  t in time..**.**
2cfd0 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e   For all version
2cfe0 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74  s of SQLite up t
2cff0 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20  o and including 
2d000 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c  3.6.23.1, a call
2d010 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2d020 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71  reset()] was req
2d030 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69  uired after sqli
2d040 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72  te3_step() retur
2d050 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20  ned anything.** 
2d060 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2d070 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61  TE_ROW] before a
2d080 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ny subsequent in
2d090 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73  vocation of.** s
2d0a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2d0b0 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74  Failure to reset
2d0c0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2d0d0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a  atement using .*
2d0e0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2d0f0 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74  ()] would result
2d100 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d   in an [SQLITE_M
2d110 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72  ISUSE] return fr
2d120 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  om.** sqlite3_st
2d130 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72  ep().  But after
2d140 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e   version 3.6.23.
2d150 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  1, sqlite3_step(
2d160 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69  ) began.** calli
2d170 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
2d180 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c  t()] automatical
2d190 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75  ly in this circu
2d1a0 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a  mstance rather.*
2d1b0 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67  * than returning
2d1c0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2d1d0 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63  .  This is not c
2d1e0 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70  onsidered a comp
2d1f0 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65  atibility.** bre
2d200 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61  ak because any a
2d210 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20  pplication that 
2d220 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e  ever receives an
2d230 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65   SQLITE_MISUSE e
2d240 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65  rror.** is broke
2d250 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e  n by definition.
2d260 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d    The [SQLITE_OM
2d270 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f  IT_AUTORESET] co
2d280 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
2d290 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  n.** can be used
2d2a0 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20   to restore the 
2d2b0 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e  legacy behavior.
2d2c0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
2d2d0 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
2d2e0 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61  </b> In the lega
2d2f0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
2d300 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2d310 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72  .** API always r
2d320 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
2d330 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51   error code, [SQ
2d340 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
2d350 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72  lowing any.** er
2d360 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
2d370 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
2d380 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2d390 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
2d3a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2d3b0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
2d3c0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
2d3d0 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
2d3e0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65  ne of the.** spe
2d3f0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
2d400 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
2d410 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
2d420 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
2d430 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
2d440 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
2d450 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
2d460 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
2d470 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
2d480 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
2d490 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
2d4a0 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
2d4b0 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72  .** using either
2d4c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d4d0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
2d4e0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2d4f0 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
2d500 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
2d510 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2d520 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2d530 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72  epare16()] inter
2d540 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  faces,.** then t
2d550 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
2d560 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61   [error codes] a
2d570 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
2d580 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
2d590 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
2d5a0 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20  use of the "v2" 
2d5b0 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
2d5c0 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74  ommended..*/.int
2d5d0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
2d5e0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2d5f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2d600 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2d610 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
2d620 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2d630 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2d640 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2d650 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2d660 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2d670 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20  .** current row 
2d680 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2d690 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  t of [prepared s
2d6a0 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
2d6b0 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61  ^If prepared sta
2d6c0 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f  tement P does no
2d6d0 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72  t have results r
2d6e0 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a  eady to return.*
2d6f0 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20  * (via calls to 
2d700 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
2d710 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  umn_int | sqlite
2d720 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66  3_column_*()] of
2d730 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20  .** interfaces) 
2d740 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74  then sqlite3_dat
2d750 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72  a_count(P) retur
2d760 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ns 0..** ^The sq
2d770 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2d780 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f  (P) routine also
2d790 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20   returns 0 if P 
2d7a0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2d7b0 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  r..** ^The sqlit
2d7c0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2d7d0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2d7e0 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f   0 if the previo
2d7f0 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  us call to.** [s
2d800 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
2d810 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2d820 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71  _DONE].  ^The sq
2d830 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2d840 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  (P).** will retu
2d850 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70  rn non-zero if p
2d860 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
2d870 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
2d880 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53  ) returned.** [S
2d890 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65  QLITE_ROW], exce
2d8a0 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f  pt in the case o
2d8b0 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e  f the [PRAGMA in
2d8c0 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d  cremental_vacuum
2d8d0 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c  ].** where it al
2d8e0 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72  ways returns zer
2d8f0 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65  o since each ste
2d900 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d  p of that multi-
2d910 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72  step.** pragma r
2d920 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73  eturns 0 columns
2d930 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
2d940 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2d950 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2d960 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )].*/.int sqlite
2d970 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
2d980 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2d990 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2d9a0 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
2d9b0 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59  Datatypes.** KEY
2d9c0 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
2d9d0 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79  XT.**.** ^(Every
2d9e0 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
2d9f0 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
2da00 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
2da10 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
2da20 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
2da30 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2da40 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
2da50 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
2da60 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
2da70 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
2da80 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
2da90 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  ULL.** </ul>)^.*
2daa0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
2dab0 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
2dac0 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
2dad0 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
2dae0 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
2daf0 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
2db00 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
2db10 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
2db20 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
2db30 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
2db40 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
2db50 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
2db60 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
2db70 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
2db80 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
2db90 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
2dba0 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f  SQLITE3_TEXT, no
2dbb0 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
2dbc0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
2dbd0 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
2dbe0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
2dbf0 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
2dc00 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
2dc10 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
2dc20 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
2dc30 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
2dc40 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
2dc50 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
2dc60 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
2dc70 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
2dc80 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
2dc90 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
2dca0 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56  PI3REF: Result V
2dcb0 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
2dcc0 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ry.** KEYWORDS: 
2dcd0 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  {column access f
2dce0 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
2dcf0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66  These routines f
2dd00 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20  orm the "result 
2dd10 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a  set" interface..
2dd20 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2dd30 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66  tines return inf
2dd40 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61  ormation about a
2dd50 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
2dd60 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
2dd70 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61   result row of a
2dd80 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65   query.  ^In eve
2dd90 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73  ry case the firs
2dda0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  t argument is a 
2ddb0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
2ddc0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2ddd0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
2dde0 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28  eing evaluated (
2ddf0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
2de00 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  t*].** that was 
2de10 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
2de20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2de30 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
2de40 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20  ts variants).** 
2de50 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61  and the second a
2de60 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
2de70 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
2de80 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
2de90 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  ormation.** shou
2dea0 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
2deb0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
2dec0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
2ded0 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69  lt set has the i
2dee0 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  ndex 0..** ^The 
2def0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2df00 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
2df10 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
2df20 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
2df30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2df40 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ()]..**.** If th
2df50 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2df60 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  does not current
2df70 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
2df80 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
2df90 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64  he.** column ind
2dfa0 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
2dfb0 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
2dfc0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
2dfd0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
2dfe0 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ay only be calle
2dff0 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20  d when the most 
2e000 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  recent call to.*
2e010 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2e020 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
2e030 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64  [SQLITE_ROW] and
2e040 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c   neither.** [sql
2e050 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f  ite3_reset()] no
2e060 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2e070 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e  ize()] have been
2e080 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65   called subseque
2e090 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ntly..** If any 
2e0a0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2e0b0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74  s are called aft
2e0c0 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  er [sqlite3_rese
2e0d0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
2e0e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2e0f0 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  or after [sqlite
2e100 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
2e110 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68  turned.** someth
2e120 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
2e130 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65  SQLITE_ROW], the
2e140 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2e150 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73  efined..** If [s
2e160 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
2e170 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
2e180 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2e190 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61  finalize()].** a
2e1a0 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  re called from a
2e1b0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
2e1c0 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74  d while any of t
2e1d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
2e1e0 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68   are pending, th
2e1f0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2e200 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
2e210 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2e220 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
2e230 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2e240 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
2e250 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
2e260 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
2e270 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
2e280 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
2e290 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20  t column.  ^The 
2e2a0 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
2e2b0 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
2e2c0 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
2e2d0 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
2e2e0 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
2e2f0 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
2e300 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54  SQLITE_NULL].  T
2e310 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
2e320 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2e330 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
2e340 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
2e350 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63   if no type.** c
2e360 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
2e370 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63  occurred as desc
2e380 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66  ribed below.  Af
2e390 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
2e3a0 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61  rsion,.** the va
2e3b0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
2e3c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e3d0 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ype() is undefin
2e3e0 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ed.  Future.** v
2e3f0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
2e400 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
2e410 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
2e420 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2e430 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
2e440 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
2e450 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  n..**.** ^If the
2e460 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
2e470 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e  B or UTF-8 strin
2e480 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
2e490 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2e4a0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
2e4b0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2e4c0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2e4d0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
2e4e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2e4f0 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73  lt is a UTF-16 s
2e500 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
2e510 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2e520 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
2e530 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
2e540 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  -8 and then retu
2e550 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2e560 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
2e570 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2e580 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
2e590 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2e5a0 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a  n_bytes() uses.*
2e5b0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
2e5c0 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
2e5d0 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
2e5e0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61  a UTF-8 string a
2e5f0 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
2e600 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2e610 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
2e620 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2e630 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
2e640 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2e650 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73  _bytes() returns
2e660 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   zero..**.** ^If
2e670 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2e680 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20   BLOB or UTF-16 
2e690 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
2e6a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e6b0 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74  ytes16().** rout
2e6c0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
2e6d0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2e6e0 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
2e6f0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2e700 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
2e710 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65  TF-8 string, the
2e720 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2e730 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65  _bytes16() conve
2e740 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
2e750 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20  g to UTF-16 and 
2e760 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
2e770 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2e780 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2e790 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
2e7a0 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
2e7b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2e7c0 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  16() uses.** [sq
2e7d0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
2e7e0 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
2e7f0 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
2e800 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72  -16 string and r
2e810 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
2e820 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2e830 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2e840 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2e850 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
2e860 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e870 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a  es16() returns z
2e880 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ero..**.** ^The 
2e890 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
2e8a0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
2e8b0 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
2e8c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2e8d0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64  umn_bytes16()] d
2e8e0 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68  o not include th
2e8f0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
2e900 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  rs at the end.**
2e910 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
2e920 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74   ^For clarity: t
2e930 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
2e940 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
2e950 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2e960 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
2e970 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
2e980 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20   are the number 
2e990 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
2e9a0 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74  he string, not t
2e9b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
2e9c0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
2e9d0 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  Strings returned
2e9e0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2e9f0 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71  mn_text() and sq
2ea00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2ea10 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65  t16(),.** even e
2ea20 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72  mpty strings, ar
2ea30 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  e always zero-te
2ea40 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
2ea50 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
2ea60 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
2ea70 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
2ea80 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
2ea90 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  B is a NULL poin
2eaa0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
2eab0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2eac0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
2ead0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61  mn_value()] is a
2eae0 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
2eaf0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2eb00 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70   object.  An unp
2eb10 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2eb20 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a  _value object.**
2eb30 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
2eb40 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
2eb50 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e  bind_value()] an
2eb60 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
2eb70 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49  t_value()]..** I
2eb80 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74  f the [unprotect
2eb90 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2eba0 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
2ebb0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
2ebc0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
2ebd0 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20   is used in any 
2ebe0 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75  other way, inclu
2ebf0 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  ding calls.** to
2ec00 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
2ec10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
2ec20 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  t()], [sqlite3_v
2ec30 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
2ec40 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
2ec50 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65  ue_bytes()], the
2ec60 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
2ec70 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2ec80 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2ec90 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e  s attempt to con
2eca0 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77  vert the value w
2ecb0 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65  here appropriate
2ecc0 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  .  ^For.** examp
2ecd0 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
2ece0 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
2ecf0 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
2ed00 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
2ed10 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
2ed20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
2ed30 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
2ed40 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
2ed50 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
2ed60 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
2ed70 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77  y.  ^(The follow
2ed80 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
2ed90 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
2eda0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70  s.** that are ap
2edb0 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
2edc0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
2edd0 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
2ede0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
2edf0 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
2ee00 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
2ee10 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
2ee20 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
2ee30 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2ee40 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2ee50 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
2ee60 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2ee70 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2ee80 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2ee90 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
2eea0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
2eeb0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
2eec0 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
2eed0 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
2eee0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2eef0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
2ef00 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20  esult is a NULL 
2ef10 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
2ef20 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2ef30 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2ef40 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
2ef50 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
2ef60 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2ef70 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
2ef80 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
2ef90 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
2efa0 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
2efb0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2efc0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2efd0 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
2efe0 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
2eff0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
2f000 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
2f010 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
2f020 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
2f030 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
2f040 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
2f050 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
2f060 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
2f070 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
2f080 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2f090 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a  [CAST] to BLOB.*
2f0a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2f0b0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2f0c0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2f0d0 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
2f0e0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2f0f0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2f100 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41  d> [CAST] to REA
2f110 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  L.** <tr><td>  T
2f120 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
2f130 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
2f140 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
2f150 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
2f160 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
2f170 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
2f180 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2f190 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
2f1a0 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
2f1b0 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
2f1c0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2f1d0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2f1e0 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
2f1f0 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
2f200 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
2f210 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
2f220 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
2f230 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65  above makes refe
2f240 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72  rence to standar
2f250 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63  d C library func
2f260 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20  tions atoi().** 
2f270 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c  and atof().  SQL
2f280 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61  ite does not rea
2f290 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75  lly use these fu
2f2a0 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73  nctions.  It has
2f2b0 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69   its.** own equi
2f2c0 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20  valent internal 
2f2d0 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61  routines.  The a
2f2e0 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29  toi() and atof()
2f2f0 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73   names are.** us
2f300 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20  ed in the table 
2f310 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20  for brevity and 
2f320 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65  because they are
2f330 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73   familiar to mos
2f340 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65  t.** C programme
2f350 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  rs..**.** Note t
2f360 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
2f370 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
2f380 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
2f390 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
2f3a0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2f3b0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
2f3c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f3d0 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
2f3e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f3f0 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
2f400 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54  nvalidated..** T
2f410 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
2f420 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61  and pointer inva
2f430 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lidations might 
2f440 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
2f450 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a  following cases:
2f460 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2f470 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2f480 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f  content is a BLO
2f490 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  B and sqlite3_co
2f4a0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a  lumn_text() or.*
2f4b0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2f4c0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
2f4d0 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72  s called.  A zer
2f4e0 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67  o-terminator mig
2f4f0 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20  ht.**      need 
2f500 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74  to be added to t
2f510 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a  he string.</li>.
2f520 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2f530 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
2f540 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71  TF-8 text and sq
2f550 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f560 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20  es16() or.**    
2f570 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2f580 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
2f590 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
2f5a0 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
2f5b0 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
2f5c0 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  TF-16.</li>.** <
2f5d0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2f5e0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
2f5f0 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
2f600 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2f610 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
2f620 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2f630 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
2f640 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
2f650 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
2f660 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f       to UTF-8.</
2f670 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
2f680 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20  ** ^Conversions 
2f690 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
2f6a0 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
2f6b0 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
2f6c0 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
2f6d0 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
2f6e0 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
2f6f0 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
2f700 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
2f710 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
2f720 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
2f730 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73  inter references
2f740 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
2f750 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
2f760 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
2f770 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
2f780 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
2f790 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
2f7a0 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
2f7b0 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
2f7c0 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
2f7d0 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
2f7e0 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
2f7f0 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  lidated..**.** T
2f800 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61  he safest and ea
2f810 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65  siest to remembe
2f820 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  r policy is to i
2f830 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
2f840 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
2f850 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
2f860 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
2f870 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2f880 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
2f890 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2f8a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2f8b0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
2f8c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2f8d0 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
2f8e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f8f0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
2f900 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
2f910 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
2f920 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2f930 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2f940 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
2f950 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
2f960 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
2f970 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
2f980 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
2f990 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f9a0 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
2f9b0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2f9c0 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
2f9d0 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
2f9e0 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
2f9f0 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
2fa00 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
2fa10 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
2fa20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fa30 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
2fa40 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
2fa50 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
2fa60 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
2fa70 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2fa80 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
2fa90 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2faa0 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
2fab0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2fac0 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
2fad0 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
2fae0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2faf0 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
2fb00 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
2fb10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2fb20 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s()..**.** ^The 
2fb30 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2fb40 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
2fb50 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
2fb60 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
2fb70 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
2fb80 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
2fb90 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
2fba0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2fbb0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2fbc0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
2fbd0 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d  alled.  ^The mem
2fbe0 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
2fbf0 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
2fc00 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66  * and BLOBs is f
2fc10 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
2fc20 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f  ly.  Do <b>not</
2fc30 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  b> pass the poin
2fc40 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
2fc50 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
2fc60 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
2fc70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2fc80 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
2fc90 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  o.** [sqlite3_fr
2fca0 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ee()]..**.** ^(I
2fcb0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2fcc0 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
2fcd0 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76  rs during the ev
2fce0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a  aluation of any.
2fcf0 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ** of these rout
2fd00 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20  ines, a default 
2fd10 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
2fd20 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
2fd30 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68  value.** is eith
2fd40 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30  er the integer 0
2fd50 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  , the floating p
2fd60 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c  oint number 0.0,
2fd70 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   or a NULL.** po
2fd80 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65  inter.  Subseque
2fd90 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
2fda0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
2fdb0 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  will return.** [
2fdc0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e  SQLITE_NOMEM].)^
2fdd0 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
2fde0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2fdf0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2fe00 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2fe10 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2fe20 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73  _bytes(sqlite3_s
2fe30 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2fe40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2fe50 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
2fe60 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2fe70 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  Col);.double sql
2fe80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
2fe90 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
2fea0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
2feb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fec0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
2fed0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
2fee0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
2fef0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
2ff00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2ff10 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
2ff20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
2ff30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ff40 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
2ff50 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
2ff60 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2ff70 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2ff80 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ff90 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2ffa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2ffb0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2ffc0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
2ffd0 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74  te3_value *sqlit
2ffe0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2fff0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30000 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  nt iCol);../*.**
30010 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72   CAPI3REF: Destr
30020 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74  oy A Prepared St
30030 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
30040 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
30050 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e  3_finalize() fun
30060 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
30070 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65  to delete a [pre
30080 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
30090 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  ..** ^If the mos
300a0 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
300b0 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
300c0 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64  ment encountered
300d0 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72   no errors.** or
300e0 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
300f0 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20  t is never been 
30100 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20  evaluated, then 
30110 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
30120 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  () returns.** SQ
30130 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68  LITE_OK.  ^If th
30140 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
30150 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74  aluation of stat
30160 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20  ement S failed, 
30170 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
30180 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75  finalize(S) retu
30190 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69  rns the appropri
301a0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
301b0 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
301c0 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a   error code]..**
301d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
301e0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75  _finalize(S) rou
301f0 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
30200 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
30210 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69  during.** the li
30220 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65  fe cycle of [pre
30230 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
30240 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74   S:.** before st
30250 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65  atement S is eve
30260 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74  r evaluated, aft
30270 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
30280 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  e calls to [sqli
30290 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72  te3_reset()], or
302a0 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a   after any call.
302b0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ** to [sqlite3_s
302c0 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73  tep()] regardles
302d0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
302e0 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  not the statemen
302f0 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  t has.** complet
30300 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a  ed execution..**
30310 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71  .** ^Invoking sq
30320 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
30330 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   on a NULL point
30340 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  er is a harmless
30350 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68   no-op..**.** Th
30360 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
30370 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72  st finalize ever
30380 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  y [prepared stat
30390 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20  ement] in order 
303a0 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f  to avoid.** reso
303b0 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20  urce leaks.  It 
303c0 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72  is a grievous er
303d0 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  ror for the appl
303e0 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74  ication to try t
303f0 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61  o use.** a prepa
30400 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66  red statement af
30410 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
30420 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20  finalized.  Any 
30430 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  use of a prepare
30440 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  d.** statement a
30450 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
30460 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72   finalized can r
30470 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
30480 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69  ed and.** undesi
30490 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73  rable behavior s
304a0 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73  uch as segfaults
304b0 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70   and heap corrup
304c0 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
304d0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
304e0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
304f0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
30500 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
30510 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
30520 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
30530 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
30540 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
30550 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
30560 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30570 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
30580 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
30590 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
305a0 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
305b0 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74  ..** ^Any SQL st
305c0 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
305d0 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
305e0 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
305f0 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
30600 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
30610 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
30620 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
30630 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
30640 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
30650 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
30660 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
30670 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ings..**.** ^The
30680 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
30690 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
306a0 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
306b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
306c0 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62  ** back to the b
306d0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
306e0 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  program..**.** ^
306f0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
30700 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
30710 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
30720 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
30730 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
30740 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
30750 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
30760 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20  DONE],.** or if 
30770 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
30780 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
30790 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
307a0 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  n S,.** then [sq
307b0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
307c0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
307d0 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  OK]..**.** ^If t
307e0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
307f0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
30800 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
30810 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
30820 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
30830 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
30840 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hen.** [sqlite3_
30850 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
30860 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
30870 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
30880 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
30890 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
308a0 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
308b0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
308c0 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c  s.** of any [sql
308d0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
308e0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
308f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30900 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] S..*/.int s
30910 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
30920 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
30930 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30940 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
30950 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
30960 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
30970 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
30980 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
30990 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
309a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
309b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
309c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
309d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
309e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
309f0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
30a00 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
30a10 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
30a20 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
30a30 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
30a40 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
30a50 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
30a60 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
30a70 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
30a80 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
30a90 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
30aa0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
30ab0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
30ac0 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e  ferences between
30ad0 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
30ae0 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20  es are the text 
30af0 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65  encoding expecte
30b00 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63  d for.** the sec
30b10 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74  ond parameter (t
30b20 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66  he name of the f
30b30 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72  unction being cr
30b40 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68  eated).** and th
30b50 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62  e presence or ab
30b60 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72  sence of a destr
30b70 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66  uctor callback f
30b80 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  or.** the applic
30b90 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
30ba0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  er..**.** ^The f
30bb0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
30bc0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
30bd0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
30be0 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
30bf0 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
30c00 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e  e added.  ^If an
30c10 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65   application use
30c20 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
30c30 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
30c40 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c  ection then appl
30c50 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
30c60 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
30c70 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74  st be added.** t
30c80 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
30c90 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72  connection separ
30ca0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ately..**.** ^Th
30cb0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
30cc0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
30cd0 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
30ce0 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
30cf0 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
30d00 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
30d10 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
30d20 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
30d30 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a  es in a UTF-8.**
30d40 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c   representation,
30d50 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
30d60 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
30d70 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  r.  ^Note that t
30d80 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74  he name.** lengt
30d90 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54  h limit is in UT
30da0 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63  F-8 bytes, not c
30db0 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54  haracters nor UT
30dc0 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a  F-16 bytes.  .**
30dd0 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f   ^Any attempt to
30de0 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
30df0 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
30e00 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
30e10 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
30e20 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65  MISUSE] being re
30e30 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
30e40 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
30e50 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
30e60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
30e70 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
30e80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
30e90 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
30ea0 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61  kes. ^If this pa
30eb0 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74  rameter is -1, t
30ec0 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
30ed0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
30ee0 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
30ef0 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
30f00 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20  ments between 0 
30f10 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a  and the limit.**
30f20 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33   set by [sqlite3
30f30 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
30f40 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
30f50 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68  RG]).  If the th
30f60 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
30f70 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31   is less than -1
30f80 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
30f90 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65   127 then the be
30fa0 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
30fb0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
30fc0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
30fd0 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
30fe0 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
30ff0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
31000 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
31010 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
31020 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
31030 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
31040 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
31050 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73   should set this
31060 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
31070 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
31080 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f  ] if the functio
31090 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
310a0 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71   invokes .** [sq
310b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
310c0 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e  16le()] on an in
310d0 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  put, or [SQLITE_
310e0 55 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a  UTF16BE] if the.
310f0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
31100 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74  n invokes [sqlit
31110 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
31120 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74  e()] on an input
31130 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  , or.** [SQLITE_
31140 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74  UTF16] if [sqlit
31150 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
31160 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b  )] is used, or [
31170 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20  SQLITE_UTF8].** 
31180 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65  otherwise.  ^The
31190 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
311a0 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
311b0 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69  ered multiple ti
311c0 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66  mes using.** dif
311d0 66 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 64  ferent preferred
311e0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c   text encodings,
311f0 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
31200 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
31210 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f  for.** each enco
31220 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d  ding..** ^When m
31230 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
31240 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
31250 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  ame function are
31260 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69   available, SQLi
31270 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20  te.** will pick 
31280 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76  the one that inv
31290 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20  olves the least 
312a0 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63  amount of data c
312b0 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
312c0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
312d0 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f  ameter may optio
312e0 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69  nally be ORed wi
312f0 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52  th [SQLITE_DETER
31300 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20  MINISTIC].** to 
31310 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20  signal that the 
31320 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c  function will al
31330 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20  ways return the 
31340 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65  same result give
31350 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e  n.** the same in
31360 70 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 69  puts within a si
31370 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
31380 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75  nt.  Most SQL fu
31390 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64  nctions are.** d
313a0 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54  eterministic.  T
313b0 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e  he built-in [ran
313c0 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74  dom()] SQL funct
313d0 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c  ion is an exampl
313e0 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69  e of a.** functi
313f0 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64  on that is not d
31400 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54  eterministic.  T
31410 68 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 20  he SQLite query 
31420 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20  planner is able 
31430 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64  to.** perform ad
31440 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a  ditional optimiz
31450 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d  ations on determ
31460 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e  inistic function
31470 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20  s, so use.** of 
31480 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45  the [SQLITE_DETE
31490 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20  RMINISTIC] flag 
314a0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77  is recommended w
314b0 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  here possible..*
314c0 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68  *.** ^(The fifth
314d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
314e0 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
314f0 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
31500 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
31510 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
31520 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
31530 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
31540 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
31550 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ata()].)^.**.** 
31560 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65  ^The sixth, seve
31570 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70  nth and eighth p
31580 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
31590 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
315a0 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
315b0 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
315c0 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
315d0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
315e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
315f0 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20  * aggregate. ^A 
31600 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
31610 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
31620 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
31630 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63  f the xFunc.** c
31640 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55  allback only; NU
31650 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74  LL pointers must
31660 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
31670 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
31680 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
31690 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20  . ^An aggregate 
316a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
316b0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
316c0 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70  ntation of xStep
316d0 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  .** and xFinal a
316e0 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  nd NULL pointer 
316f0 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66  must be passed f
31700 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65  or xFunc. ^To de
31710 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67  lete an existing
31720 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
31730 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
31740 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ass NULL pointer
31750 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  s for all three 
31760 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  function.** call
31770 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  backs..**.** ^(I
31780 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61  f the ninth para
31790 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
317a0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
317b0 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  _v2() is not NUL
317c0 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  L,.** then it is
317d0 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
317e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
317f0 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a  data pointer. .*
31800 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72  * The destructor
31810 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
31820 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
31830 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72   deleted, either
31840 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65   by being.** ove
31850 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20  rloaded or when 
31860 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
31870 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29  nection closes.)
31880 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75  ^.** ^The destru
31890 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76  ctor is also inv
318a0 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c  oked if the call
318b0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
318c0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
318d0 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57  2() fails..** ^W
318e0 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74  hen the destruct
318f0 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  or callback of t
31900 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74  he tenth paramet
31910 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69  er is invoked, i
31920 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61  t.** is passed a
31930 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
31940 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79   which is a copy
31950 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
31960 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69  ion data .** poi
31970 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74  nter which was t
31980 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
31990 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
319a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
319b0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ()..**.** ^It is
319c0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65   permitted to re
319d0 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20  gister multiple 
319e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
319f0 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66  of the same.** f
31a00 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68  unctions with th
31a10 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20  e same name but 
31a20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66  with either diff
31a30 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66  ering numbers of
31a40 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  .** arguments or
31a50 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65   differing prefe
31a60 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
31a70 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  ngs.  ^SQLite wi
31a80 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
31a90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61  plementation tha
31aa0 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d  t most closely m
31ab0 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69  atches the way i
31ac0 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53  n which the.** S
31ad0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  QL function is u
31ae0 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  sed.  ^A functio
31af0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
31b00 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61   with a non-nega
31b10 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72  tive.** nArg par
31b20 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74  ameter is a bett
31b30 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
31b40 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
31b50 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20  ntation with.** 
31b60 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e  a negative nArg.
31b70 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68    ^A function wh
31b80 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  ere the preferre
31b90 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  d text encoding.
31ba0 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64  ** matches the d
31bb0 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
31bc0 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20   is a better.** 
31bd0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
31be0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
31bf0 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
31c00 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66  erent.  .** ^A f
31c10 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
31c20 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
31c30 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e  rence is between
31c40 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46   UTF16le and UTF
31c50 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f  16be.** is a clo
31c60 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ser match than a
31c70 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
31c80 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
31c90 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65  ference is.** be
31ca0 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55  tween UTF8 and U
31cb0 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69  TF16..**.** ^Bui
31cc0 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20  lt-in functions 
31cd0 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65  may be overloade
31ce0 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61  d by new applica
31cf0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
31d00 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  ctions..**.** ^A
31d10 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
31d20 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
31d30 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63  s permitted to c
31d40 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  all other.** SQL
31d50 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20  ite interfaces. 
31d60 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63   However, such c
31d70 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a  alls must not.**
31d80 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
31d90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e  ase connection n
31da0 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72  or finalize or r
31db0 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
31dc0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
31dd0 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63  n which the func
31de0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
31df0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
31e00 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
31e10 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
31e20 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
31e30 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
31e40 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
31e50 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
31e60 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
31e70 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
31e80 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
31e90 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
31ea0 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
31eb0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
31ec0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
31ed0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
31ee0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
31ef0 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
31f00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31f10 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  nction16(.  sqli
31f20 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
31f30 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e   void *zFunction
31f40 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
31f50 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
31f60 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
31f70 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
31f80 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31f90 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
31fa0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
31fb0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
31fc0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
31fd0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
31fe0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
31ff0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
32000 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
32010 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
32020 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
32030 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
32040 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
32050 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
32060 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
32070 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
32080 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
32090 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
320a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
320b0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
320c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
320d0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
320e0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
320f0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
32100 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f  _context*),.  vo
32110 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
32120 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
32130 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e  API3REF: Text En
32140 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68  codings.**.** Th
32150 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
32160 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
32170 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
32180 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
32190 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
321a0 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
321b0 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
321c0 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
321d0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
321e0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
321f0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
32200 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
32210 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
32220 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
32230 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
32240 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
32250 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
32260 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
32270 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72      5    /* Depr
32280 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e  ecated */.#defin
32290 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
322a0 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
322b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
322c0 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
322d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
322e0 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73  : Function Flags
322f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
32300 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52  stants may be OR
32310 65 64 20 74 6f 67 65 74 68 65 72 20 77 69 74 68  ed together with
32320 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
32330 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72 72 65  _UTF8 | preferre
32340 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  d text encoding]
32350 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61   as the fourth a
32360 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73  rgument.** to [s
32370 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
32380 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  nction()], [sqli
32390 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
323a0 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
323b0 5b 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 29 5d 2e 0a  function_v2()]..
323d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
323e0 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20  E_DETERMINISTIC 
323f0 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20     0x800../*.** 
32400 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63  CAPI3REF: Deprec
32410 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ated Functions.*
32420 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a  * DEPRECATED.**.
32430 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
32440 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74  ns are [deprecat
32450 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74  ed].  In order t
32460 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61  o maintain.** ba
32470 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
32480 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72  ility with older
32490 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e   code, these fun
324a0 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
324b0 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72  .** to be suppor
324c0 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ted.  However, n
324d0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
324e0 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
324f0 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
32500 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
32510 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70  help encourage p
32520 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a  eople to avoid.*
32530 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75  * using these fu
32540 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20  nctions, we are 
32550 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c  not going to tel
32560 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20  l you what they 
32570 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  do..*/.#ifndef S
32580 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45  QLITE_OMIT_DEPRE
32590 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50  CATED.SQLITE_DEP
325a0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
325b0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
325c0 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
325d0 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  ext*);.SQLITE_DE
325e0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
325f0 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
32600 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
32610 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
32620 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73  nt sqlite3_trans
32630 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  fer_bindings(sql
32640 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69  ite3_stmt*, sqli
32650 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
32660 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
32670 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
32680 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
32690 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
326a0 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74  D void sqlite3_t
326b0 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f  hread_cleanup(vo
326c0 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
326d0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
326e0 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
326f0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
32700 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29  lite3_int64,int)
32710 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
32720 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71          void*,sq
32730 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65  lite3_int64);.#e
32740 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
32750 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
32760 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72  SQL Function Par
32770 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a  ameter Values.**
32780 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61  .** The C-langua
32790 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ge implementatio
327a0 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f  n of SQL functio
327b0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
327c0 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73  s uses.** this s
327d0 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20  et of interface 
327e0 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65  routines to acce
327f0 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ss the parameter
32800 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68   values on.** th
32810 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  e function or ag
32820 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54  gregate..**.** T
32830 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63  he xFunc (for sc
32840 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20  alar functions) 
32850 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67  or xStep (for ag
32860 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65  gregates) parame
32870 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ters.** to [sqli
32880 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32890 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
328a0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
328b0 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69  ion16()].** defi
328c0 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  ne callbacks tha
328d0 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
328e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
328f0 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a  d aggregates..**
32900 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   The 3rd paramet
32910 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c  er to these call
32920 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61  backs is an arra
32930 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
32940 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73  .** [protected s
32950 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
32960 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73  jects.  There is
32970 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   one [sqlite3_va
32980 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a  lue] object for.
32990 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65  ** each paramete
329a0 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  r to the SQL fun
329b0 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f  ction.  These ro
329c0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
329d0 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61  to.** extract va
329e0 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73  lues from the [s
329f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
32a00 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  jects..**.** The
32a10 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
32a20 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74   only with [prot
32a30 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
32a40 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
32a50 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
32a60 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  use these routin
32a70 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74  es on an [unprot
32a80 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
32a90 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  lue].** object r
32aa0 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
32ab0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
32ac0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
32ad0 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
32ae0 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
32af0 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63  ding [column acc
32b00 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a  ess functions].*
32b10 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  * except that th
32b20 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
32b30 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74  e a single [prot
32b40 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
32b50 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70  lue] object.** p
32b60 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
32b70 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  f a [sqlite3_stm
32b80 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
32b90 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
32ba0 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
32bb0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
32bc0 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
32bd0 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
32be0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
32bf0 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
32c00 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
32c10 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
32c20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
32c30 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
32c40 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
32c50 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
32c60 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
32c70 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69  ract UTF-16 stri
32c80 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61  ngs as big-endia
32c90 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64  n and little-end
32ca0 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
32cb0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
32cc0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
32cd0 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72  ric_type() inter
32ce0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
32cf0 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69   apply.** numeri
32d00 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68  c affinity to th
32d10 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d  e value.  This m
32d20 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74  eans that an att
32d30 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20  empt is.** made 
32d40 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
32d50 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67  alue to an integ
32d60 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70  er or floating p
32d70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63  oint.  If.** suc
32d80 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  h a conversion i
32d90 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f  s possible witho
32da0 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72  ut loss of infor
32db0 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72  mation (in other
32dc0 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68  .** words, if th
32dd0 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72  e value is a str
32de0 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
32df0 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
32e00 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72   then the conver
32e10 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  sion is performe
32e20 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f  d.  Otherwise no
32e30 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
32e40 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  rs..** The [SQLI
32e50 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
32e60 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e  atype] after con
32e70 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72  version is retur
32e80 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65  ned.)^.**.** Ple
32e90 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c  ase pay particul
32ea0 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20  ar attention to 
32eb0 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68  the fact that th
32ec0 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e  e pointer return
32ed0 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
32ee0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
32ef0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
32f00 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
32f10 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
32f20 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
32f30 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
32f40 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
32f50 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
32f60 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
32f70 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
32f80 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
32f90 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
32fa0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
32fb0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
32fc0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  )]..**.** These 
32fd0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
32fe0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
32ff0 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
33000 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
33010 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65  ion that supplie
33020 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  d the [sqlite3_v
33030 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72  alue*] parameter
33040 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  s..*/.const void
33050 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
33060 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c  blob(sqlite3_val
33070 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
33080 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71  3_value_bytes(sq
33090 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
330a0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
330b0 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
330c0 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65  _value*);.double
330d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
330e0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  ouble(sqlite3_va
330f0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
33100 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c  e3_value_int(sql
33110 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71  ite3_value*);.sq
33120 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
33130 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28  te3_value_int64(
33140 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
33150 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
33160 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61  char *sqlite3_va
33170 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33  lue_text(sqlite3
33180 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
33190 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
331a0 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74  lue_text16(sqlit
331b0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
331c0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
331d0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73  value_text16le(s
331e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
331f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
33200 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
33210 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  be(sqlite3_value
33220 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
33230 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74  value_type(sqlit
33240 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
33250 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
33260 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74  meric_type(sqlit
33270 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
33280 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
33290 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75  ain Aggregate Fu
332a0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a  nction Context.*
332b0 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74  *.** Implementat
332c0 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74  ions of aggregat
332d0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
332e0 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74  use this.** rout
332f0 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ine to allocate 
33300 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69  memory for stori
33310 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a  ng their state..
33320 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
33330 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65   time the sqlite
33340 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
33350 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
33360 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66   is called .** f
33370 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
33380 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
33390 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c  on, SQLite.** al
333a0 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d  locates N of mem
333b0 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20  ory, zeroes out 
333c0 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64  that memory, and
333d0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
333e0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77  er.** to the new
333f0 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63   memory. ^On sec
33400 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
33410 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  nt calls to.** s
33420 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
33430 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74  _context() for t
33440 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
33450 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
33460 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65  nce,.** the same
33470 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72   buffer is retur
33480 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67  ned.  Sqlite3_ag
33490 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
334a0 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a  ) is normally.**
334b0 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72   called once for
334c0 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
334d0 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61   of the xStep ca
334e0 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20  llback and then 
334f0 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65  one.** last time
33500 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c   when the xFinal
33510 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
33520 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f  oked.  ^(When no
33530 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61   rows match.** a
33540 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  n aggregate quer
33550 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63  y, the xStep() c
33560 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61  allback of the a
33570 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
33580 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
33590 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c  ion is never cal
335a0 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29  led and xFinal()
335b0 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74   is called exact
335c0 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74  ly once..** In t
335d0 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69  hose cases, sqli
335e0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
335f0 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65  ntext() might be
33600 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a   called for the.
33610 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72  ** first time fr
33620 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c  om within xFinal
33630 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().)^.**.** ^The
33640 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
33650 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
33660 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
33670 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a  a NULL pointer .
33680 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61  ** when first ca
33690 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73  lled if N is les
336a0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
336b0 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20  to zero or if a 
336c0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
336d0 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  te error occurs.
336e0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f  .**.** ^(The amo
336f0 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c  unt of space all
33700 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
33710 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
33720 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64  ext(C,N) is.** d
33730 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
33740 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20   N parameter on 
33750 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c  first successful
33760 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67   call.  Changing
33770 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
33780 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74   N in subsequent
33790 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
337a0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
337b0 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74  xt() within.** t
337c0 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
337d0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
337e0 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73  nce will not res
337f0 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a  ize the memory.*
33800 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20  * allocation.)^ 
33810 20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e   Within the xFin
33820 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20  al callback, it 
33830 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20  is customary to 
33840 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61  set.** N=0 in ca
33850 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  lls to sqlite3_a
33860 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
33870 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f  (C,N) so that no
33880 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d   .** pointless m
33890 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
338a0 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e  s occur..**.** ^
338b0 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
338c0 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d  ally frees the m
338d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20  emory allocated 
338e0 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61  by .** sqlite3_a
338f0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
33900 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72  () when the aggr
33910 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63  egate query conc
33920 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ludes..**.** The
33930 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
33940 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20   must be a copy 
33950 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
33960 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c  e3_context | SQL
33970 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78   function contex
33980 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66  t] that is the f
33990 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a  irst parameter.*
339a0 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f  * to the xStep o
339b0 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
339c0 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69  k routine that i
339d0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67  mplements the ag
339e0 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74  gregate.** funct
339f0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
33a00 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
33a10 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
33a20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
33a30 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
33a40 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
33a50 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
33a60 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
33a70 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
33a80 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
33a90 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
33aa0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33ab0 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
33ac0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
33ad0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65  ^The sqlite3_use
33ae0 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  r_data() interfa
33af0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
33b00 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
33b10 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65  ter that was the
33b20 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d   pUserData param
33b30 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61  eter (the 5th pa
33b40 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
33b50 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
33b60 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
33b70 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
33b80 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
33b90 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
33ba0 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
33bb0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
33bc0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
33bd0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ed function..**.
33be0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
33bf0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
33c00 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
33c10 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
33c20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
33c30 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
33c40 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
33c50 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73  void *sqlite3_us
33c60 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f  er_data(sqlite3_
33c70 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
33c80 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
33c90 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
33ca0 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
33cb0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33cc0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
33cd0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
33ce0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
33cf0 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
33d00 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
33d10 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
33d20 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
33d30 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
33d40 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33d50 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
33d60 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
33d70 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
33d80 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
33d90 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
33da0 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
33db0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
33dc0 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  ion..*/.sqlite3 
33dd0 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  *sqlite3_context
33de0 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
33df0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
33e00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
33e10 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72  unction Auxiliar
33e20 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65  y Data.**.** The
33e30 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  se functions may
33e40 20 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e   be used by (non
33e50 2d 61 67 67 72 65 67 61 74 65 29 20 53 51 4c 20  -aggregate) SQL 
33e60 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20  functions to.** 
33e70 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61  associate metada
33e80 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
33e90 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
33ea0 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
33eb0 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
33ec0 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
33ed0 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
33ee0 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
33ef0 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
33f00 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
33f10 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
33f20 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
33f30 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
33f40 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70  erved.  An examp
33f50 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74  le.** of where t
33f60 68 69 73 20 6d 69 67 68 74 20 62 65 20 75 73 65  his might be use
33f70 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65 67 75  ful is in a regu
33f80 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d  lar-expression m
33f90 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  atching.** funct
33fa0 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65  ion. The compile
33fb0 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  d version of the
33fc0 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
33fd0 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 65  ion can be store
33fe0 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61  d as.** metadata
33ff0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
34000 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72   the pattern str
34010 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61  ing.  .** Then a
34020 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 61  s long as the pa
34030 74 74 65 72 6e 20 73 74 72 69 6e 67 20 72 65 6d  ttern string rem
34040 61 69 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a  ains the same,.*
34050 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 72  * the compiled r
34060 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
34070 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
34080 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
34090 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
340a0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e  e same function.
340b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
340c0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
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 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
340f0 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a   the metadata.**
34100 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74   associated by t
34110 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
34120 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f  uxdata() functio
34130 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61  n with the Nth a
34140 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65  rgument.** value
34150 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
34160 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
34170 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65 20  tion. ^If there 
34180 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a  is no metadata.*
34190 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
341a0 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 61  h the function a
341b0 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 73 71  rgument, this sq
341c0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
341d0 61 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  a() interface.**
341e0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
341f0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
34200 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
34210 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
34220 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73   interface saves
34230 20 50 20 61 73 20 6d 65 74 61 64 61 74 61 20 66   P as metadata f
34240 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61  or the N-th.** a
34250 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  rgument of the a
34260 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
34270 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53  ed function.  ^S
34280 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
34290 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65  ls to sqlite3_ge
342a0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 20 72  t_auxdata(C,N) r
342b0 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 68 65  eturn P from the
342c0 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20   most recent.** 
342d0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
342e0 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c  ata(C,N,P,X) cal
342f0 6c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74  l if the metadat
34300 61 20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69 64  a is still valid
34310 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74   or.** NULL if t
34320 68 65 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  he metadata has 
34330 62 65 65 6e 20 64 69 73 63 61 72 64 65 64 2e 0a  been discarded..
34340 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 68 20 63  ** ^After each c
34350 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
34360 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
34370 2c 58 29 20 77 68 65 72 65 20 58 20 69 73 20 6e  ,X) where X is n
34380 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69  ot NULL,.** SQLi
34390 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
343a0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75  he destructor fu
343b0 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 20 70 61  nction X with pa
343c0 72 61 6d 65 74 65 72 20 50 20 65 78 61 63 74 6c  rameter P exactl
343d0 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20  y.** once, when 
343e0 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
343f0 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51  discarded..** SQ
34400 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20  Lite is free to 
34410 64 69 73 63 61 72 64 20 74 68 65 20 6d 65 74 61  discard the meta
34420 64 61 74 61 20 61 74 20 61 6e 79 20 74 69 6d 65  data at any time
34430 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c  , including: <ul
34440 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74  >.** <li> when t
34450 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
34460 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
34470 74 65 72 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a  ter changes, or.
34480 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71  ** <li> when [sq
34490 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
344a0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
344b0 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
344c0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
344d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
344e0 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20  or.** <li> when 
344f0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
34500 61 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ata() is invoked
34510 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 73 61   again on the sa
34520 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72  me parameter, or
34530 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20  .** <li> during 
34540 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c  the original sql
34550 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
34560 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d  () call when a m
34570 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20 61  emory .**      a
34580 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
34590 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a  occurs. </ul>)^.
345a0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c  **.** Note the l
345b0 61 73 74 20 62 75 6c 6c 65 74 20 69 6e 20 70 61  ast bullet in pa
345c0 72 74 69 63 75 6c 61 72 2e 20 20 54 68 65 20 64  rticular.  The d
345d0 65 73 74 72 75 63 74 6f 72 20 58 20 69 6e 20 0a  estructor X in .
345e0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
345f0 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
34600 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
34610 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
34620 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74  ore the.** sqlit
34630 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
34640 20 69 6e 74 65 72 66 61 63 65 20 65 76 65 6e 20   interface even 
34650 72 65 74 75 72 6e 73 2e 20 20 48 65 6e 63 65 20  returns.  Hence 
34660 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
34670 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20  ata().** should 
34680 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 72 20 74  be called near t
34690 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 75  he end of the fu
346a0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
346b0 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a  ation and the.**
346c0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
346d0 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
346e0 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75 73 65  not make any use
346f0 20 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a 20 73   of P after.** s
34700 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
34710 74 61 28 29 20 68 61 73 20 62 65 65 6e 20 63 61  ta() has been ca
34720 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  lled..**.** ^(In
34730 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64   practice, metad
34740 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
34750 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
34760 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66  n calls for.** f
34770 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
34780 72 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 70  rs that are comp
34790 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e  ile-time constan
347a0 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69  ts, including li
347b0 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20  teral.** values 
347c0 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d  and [parameters]
347d0 20 61 6e 64 20 65 78 70 72 65 73 73 69 6f 6e 73   and expressions
347e0 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74   composed from t
347f0 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a  he same.)^.**.**
34800 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
34810 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
34820 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
34830 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
34840 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
34850 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
34860 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
34870 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
34880 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
34890 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  N);.void sqlite3
348a0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
348b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
348c0 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69  nt N, void*, voi
348d0 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a  d (*)(void*));..
348e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
348f0 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e   Constants Defin
34900 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74  ing Special Dest
34910 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a  ructor Behavior.
34920 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
34930 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66  special values f
34940 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  or the destructo
34950 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
34960 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69   in as the.** fi
34970 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  nal argument to 
34980 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
34990 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
349a0 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20  ob()].  ^If the 
349b0 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72  destructor.** ar
349c0 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45  gument is SQLITE
349d0 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e  _STATIC, it mean
349e0 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
349f0 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f  nt pointer is co
34a00 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69  nstant.** and wi
34a10 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e  ll never change.
34a20 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65    It does not ne
34a30 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79  ed to be destroy
34a40 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c  ed.  ^The.** SQL
34a50 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61  ITE_TRANSIENT va
34a60 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74  lue means that t
34a70 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20  he content will 
34a80 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e  likely change in
34a90 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74  .** the near fut
34aa0 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c  ure and that SQL
34ab0 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20  ite should make 
34ac0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
34ad0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
34ae0 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65  ontent before re
34af0 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  turning..**.** T
34b00 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65  he typedef is ne
34b10 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20  cessary to work 
34b20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20  around problems 
34b30 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b  in certain.** C+
34b40 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a  + compilers..*/.
34b50 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
34b60 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
34b70 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a  r_type)(void*);.
34b80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
34b90 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c  TATIC      ((sql
34ba0 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
34bb0 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20  type)0).#define 
34bc0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
34bd0 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
34be0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29  tructor_type)-1)
34bf0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34c00 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65  : Setting The Re
34c10 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46  sult Of An SQL F
34c20 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68  unction.**.** Th
34c30 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
34c40 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
34c50 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
34c60 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
34c70 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
34c80 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
34c90 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
34ca0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
34cb0 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
34cc0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
34cd0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
34ce0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
34cf0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
34d00 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
34d10 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
34d20 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d   like the [param
34d30 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61  eter binding] fa
34d40 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74  mily of.** funct
34d50 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e  ions used to bin
34d60 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
34d70 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
34d80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34d90 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
34da0 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  the [SQL paramet
34db0 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  er] documentatio
34dc0 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
34dd0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
34de0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34df0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69  _result_blob() i
34e00 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
34e10 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
34e20 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
34e30 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
34e40 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20   to be the BLOB 
34e50 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73  whose content is
34e60 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62   pointed.** to b
34e70 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  y the second par
34e80 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68  ameter and which
34e90 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67   is N bytes long
34ea0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
34eb0 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
34ec0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
34ed0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
34ee0 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  roblob() interfa
34ef0 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75  ces set the resu
34f00 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
34f10 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34f20 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
34f30 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e  a BLOB containin
34f40 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79  g all zero.** by
34f50 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20  tes and N bytes 
34f60 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e  in size, where N
34f70 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
34f80 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
34f90 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
34fa0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
34fb0 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  uble() interface
34fc0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
34fd0 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
34fe0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34ff0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
35000 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
35010 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a  value specified.
35020 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72  ** by its 2nd ar
35030 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
35040 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35050 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
35060 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35070 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
35080 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
35090 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
350a0 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
350b0 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a  an exception..**
350c0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
350d0 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
350e0 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
350f0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
35100 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35110 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
35120 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
35130 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
35140 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
35150 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69  sage.  ^SQLite i
35160 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72  nterprets the er
35170 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73  ror.** message s
35180 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
35190 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
351a0 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c  ) as UTF-8. ^SQL
351b0 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
351c0 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
351d0 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
351e0 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
351f0 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  F-16 in native.*
35200 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e  * byte order.  ^
35210 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
35220 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
35230 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
35240 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
35250 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
35260 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
35270 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
35280 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
35290 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
352a0 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
352b0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
352c0 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
352d0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
352e0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
352f0 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73  _error() or.** s
35300 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35310 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e  ror16() is non-n
35320 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
35330 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d  ite takes that m
35340 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f  any.** bytes (no
35350 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72  t characters) fr
35360 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
35370 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f  eter as the erro
35380 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54  r message..** ^T
35390 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
353a0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
353b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
353c0 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
353d0 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
353e0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
353f0 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
35400 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
35410 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
35420 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
35430 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
35440 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
35450 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
35460 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
35470 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68  out harm..** ^Th
35480 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
35490 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75  _error_code() fu
354a0 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74  nction changes t
354b0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
354c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
354d0 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20  ite as a result 
354e0 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61  of an error in a
354f0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20   function.  ^By 
35500 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
35510 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
35520 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20  LITE_ERROR.  ^A 
35530 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
35540 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
35550 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
35560 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35570 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20  rror16() resets 
35580 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74  the error code t
35590 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a  o SQLITE_ERROR..
355a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
355b0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
355c0 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61  toobig() interfa
355d0 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
355e0 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20   to throw an.** 
355f0 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67  error indicating
35600 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f   that a string o
35610 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f  r BLOB is too lo
35620 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e  ng to represent.
35630 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35640 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
35650 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61  _nomem() interfa
35660 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
35670 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20   to throw an.** 
35680 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67  error indicating
35690 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61   that a memory a
356a0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
356b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
356c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
356d0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
356e0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
356f0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
35700 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
35710 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
35720 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64  he 32-bit signed
35730 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
35740 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
35750 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  nd argument..** 
35760 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
35770 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65  ult_int64() inte
35780 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
35790 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
357a0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
357b0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
357c0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d  on to be the 64-
357d0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
357e0 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
357f0 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
35800 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
35810 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
35820 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  _null() interfac
35830 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
35840 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
35850 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
35860 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
35870 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  o be NULL..**.**
35880 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
35890 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c  sult_text(), sql
358a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
358b0 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  16(),.** sqlite3
358c0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
358d0 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
358e0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
358f0 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
35900 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76  set the return v
35910 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c  alue of the appl
35920 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
35930 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  function to be.*
35940 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  * a text string 
35950 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65  which is represe
35960 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55  nted as UTF-8, U
35970 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
35980 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d  e order,.** UTF-
35990 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e  16 little endian
359a0 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20  , or UTF-16 big 
359b0 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
359c0 76 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  vely..** ^The sq
359d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
359e0 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
359f0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
35a00 76 61 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 61  value of an.** a
35a10 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35a20 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
35a30 65 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  e a text string 
35a40 69 6e 20 61 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a  in an encoding.*
35a50 2a 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  * specified by t
35a60 68 65 20 66 69 66 74 68 20 28 61 6e 64 20 6c 61  he fifth (and la
35a70 73 74 29 20 70 61 72 61 6d 65 74 65 72 2c 20 77  st) parameter, w
35a80 68 69 63 68 20 6d 75 73 74 20 62 65 20 6f 6e 65  hich must be one
35a90 0a 2a 2a 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55  .** of [SQLITE_U
35aa0 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
35ab0 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  F16], [SQLITE_UT
35ac0 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49  F16BE], or [SQLI
35ad0 54 45 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20  TE_UTF16LE]..** 
35ae0 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68  ^SQLite takes th
35af0 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
35b00 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
35b10 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
35b20 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
35b30 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
35b40 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
35b50 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ces..** ^If the 
35b60 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
35b70 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
35b80 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
35b90 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74  aces.** is negat
35ba0 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ive, then SQLite
35bb0 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65   takes result te
35bc0 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  xt from the 2nd 
35bd0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72  parameter.** thr
35be0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
35bf0 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
35c00 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
35c10 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
35c20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
35c30 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
35c40 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
35c50 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
35c60 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
35c70 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
35c80 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
35c90 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
35ca0 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
35cb0 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
35cc0 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
35cd0 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20  nction result.  
35ce0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
35cf0 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  eter is non-nega
35d00 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a  tive, then it.**
35d10 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74   must be the byt
35d20 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68  e offset into th
35d30 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74  e string where t
35d40 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
35d50 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61  r would.** appea
35d60 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20  r if the string 
35d70 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e  where NUL termin
35d80 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
35d90 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
35da0 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72  ur.** in the str
35db0 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66  ing at a byte of
35dc0 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73  fset that is les
35dd0 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65  s than the value
35de0 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70   of the 3rd.** p
35df0 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74  arameter, then t
35e00 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
35e10 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e  ing will contain
35e20 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61   embedded NULs a
35e30 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  nd the.** result
35e40 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
35e50 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72  operating on str
35e60 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64  ings with embedd
35e70 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
35e80 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ined..** ^If the
35e90 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
35ea0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
35eb0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
35ec0 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
35ed0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
35ee0 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  is a non-NULL po
35ef0 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
35f00 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a  te calls that.**
35f10 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65   function as the
35f20 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
35f30 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
35f40 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68  result when it h
35f50 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75  as.** finished u
35f60 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
35f70 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
35f80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
35f90 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
35fa0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
35fb0 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  s or to.** sqlit
35fc0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
35fd0 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
35fe0 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54  nstant SQLITE_ST
35ff0 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74  ATIC, then SQLit
36000 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61  e.** assumes tha
36010 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  t the text or BL
36020 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20  OB result is in 
36030 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61  constant space a
36040 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63  nd does not.** c
36050 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  opy the content 
36060 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  of the parameter
36070 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74   nor call a dest
36080 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f  ructor on the co
36090 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74  ntent.** when it
360a0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
360b0 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
360c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
360d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
360e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
360f0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
36100 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
36110 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
36120 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
36130 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  nt SQLITE_TRANSI
36140 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69  ENT.** then SQLi
36150 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
36160 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  of the result in
36170 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65  to space obtaine
36180 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b  d from.** from [
36190 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
361a0 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75  ] before it retu
361b0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
361c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
361d0 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
361e0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
361f0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
36200 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
36210 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
36220 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70  copy the.** [unp
36230 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
36240 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73  _value] object s
36250 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
36260 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
36270 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
36280 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
36290 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
362a0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
362b0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
362c0 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  so that the [sql
362d0 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63  ite3_value] spec
362e0 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72  ified in the par
362f0 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67  ameter may chang
36300 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c  e or.** be deall
36310 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c  ocated after sql
36320 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
36330 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68  e() returns with
36340 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20  out harm..** ^A 
36350 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
36360 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
36370 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75   may always be u
36380 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20  sed where an.** 
36390 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
363a0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
363b0 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20  ct is required, 
363c0 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e  so either.** kin
363d0 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  d of [sqlite3_va
363e0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20  lue] object can 
363f0 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69  be used with thi
36400 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
36410 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74  ** If these rout
36420 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
36430 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20  from within the 
36440 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
36450 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  .** than the one
36460 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
36470 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
36480 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ned function tha
36490 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68  t received.** th
364a0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  e [sqlite3_conte
364b0 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  xt] pointer, the
364c0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
364d0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20  efined..*/.void 
364e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
364f0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
36500 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
36510 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
36520 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
36530 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
36540 62 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  b64(sqlite3_cont
36550 65 78 74 2a 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ext*,const void*
36560 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c  ,sqlite3_uint64,
36570 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
36580 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
36590 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69  sult_double(sqli
365a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f  te3_context*, do
365b0 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69  uble);.void sqli
365c0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
365d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
365e0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
365f0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
36600 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
36610 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
36620 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
36630 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
36640 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36650 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f  _toobig(sqlite3_
36660 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
36670 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36680 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74  rror_nomem(sqlit
36690 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
366a0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
366b0 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c  t_error_code(sql
366c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
366d0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
366e0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c  3_result_int(sql
366f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
36700 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
36710 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73  3_result_int64(s
36720 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36730 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
36740 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
36750 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  sult_null(sqlite
36760 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
36770 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36780 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  _text(sqlite3_co
36790 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
367a0 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  ar*, int, void(*
367b0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
367c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
367d0 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  ext64(sqlite3_co
367e0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
367f0 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
36800 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
36810 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
36820 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75  oid(*)(void*), u
36830 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63  nsigned char enc
36840 6f 64 69 6e 67 29 3b 0a 76 6f 69 64 20 73 71 6c  oding);.void sql
36850 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36860 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
36870 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
36880 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
36890 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
368a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
368b0 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
368c0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
368d0 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
368e0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
368f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36900 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
36910 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
36920 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
36930 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
36940 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
36950 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
36960 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
36970 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  lue*);.void sqli
36980 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
36990 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
369a0 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f  ext*, int n);../
369b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
369c0 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74  efine New Collat
369d0 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a  ing Sequences.**
369e0 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
369f0 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65  ions add, remove
36a00 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63  , or modify a [c
36a10 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69  ollation] associ
36a20 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ated.** with the
36a30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36a40 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
36a50 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
36a60 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
36a70 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
36a80 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54  ollation is a UT
36a90 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f  F-8 string.** fo
36aa0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
36ab0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64  _collation() and
36ac0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
36ad0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a  collation_v2().*
36ae0 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73  * and a UTF-16 s
36af0 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
36b00 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73  byte order for s
36b10 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36b20 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20  llation16()..** 
36b30 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73  ^Collation names
36b40 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71   that compare eq
36b50 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  ual according to
36b60 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63   [sqlite3_strnic
36b70 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e  mp()] are.** con
36b80 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 74 68  sidered to be th
36b90 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a  e same name..**.
36ba0 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20 61  ** ^(The third a
36bb0 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65  rgument (eTextRe
36bc0 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f  p) must be one o
36bd0 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a  f the constants:
36be0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
36bf0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a   [SQLITE_UTF8],.
36c00 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
36c10 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69  UTF16LE],.** <li
36c20 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  > [SQLITE_UTF16B
36c30 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
36c40 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a  ITE_UTF16], or.*
36c50 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
36c60 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a  TF16_ALIGNED]..*
36c70 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68  * </ul>)^.** ^Th
36c80 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d  e eTextRep argum
36c90 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ent determines t
36ca0 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73  he encoding of s
36cb0 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a  trings passed.**
36cc0 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
36cd0 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
36ce0 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a  ack, xCallback..
36cf0 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
36d00 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49  UTF16] and [SQLI
36d10 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
36d20 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65  ] values for eTe
36d30 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73  xtRep.** force s
36d40 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46  trings to be UTF
36d50 31 36 20 77 69 74 68 20 6e 61 74 69 76 65 20 62  16 with native b
36d60 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54  yte order..** ^T
36d70 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  he [SQLITE_UTF16
36d80 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20  _ALIGNED] value 
36d90 66 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f 72  for eTextRep for
36da0 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62  ces strings to b
36db0 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76  egin.** on an ev
36dc0 65 6e 20 62 79 74 65 20 61 64 64 72 65 73 73 2e  en byte address.
36dd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
36de0 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72  th argument, pAr
36df0 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61  g, is an applica
36e00 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
36e10 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
36e20 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74  .** through as t
36e30 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
36e40 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  t to the collati
36e50 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ng function call
36e60 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  back..**.** ^The
36e70 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c   fifth argument,
36e80 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61   xCallback, is a
36e90 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
36ea0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36eb0 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65  on..** ^Multiple
36ec0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
36ed0 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69  ions can be regi
36ee0 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
36ef0 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a   same name but.*
36f00 2a 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  * with different
36f10 20 65 54 65 78 74 52 65 70 20 70 61 72 61 6d 65   eTextRep parame
36f20 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20  ters and SQLite 
36f30 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76  will use whichev
36f40 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  er.** function r
36f50 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73  equires the leas
36f60 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
36f70 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e   transformation.
36f80 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c  .** ^If the xCal
36f90 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69  lback argument i
36fa0 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  s NULL then the 
36fb0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36fc0 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64  on is.** deleted
36fd0 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c  .  ^When all col
36fe0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
36ff0 20 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65   having the same
37000 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65   name are delete
37010 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61  d,.** that colla
37020 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  tion is no longe
37030 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  r usable..**.** 
37040 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66  ^The collating f
37050 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
37060 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
37070 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70   a copy of the p
37080 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74  Arg .** applicat
37090 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
370a0 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74   and with two st
370b0 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63  rings in the enc
370c0 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a  oding specified.
370d0 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78 74 52  ** by the eTextR
370e0 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  ep argument.  Th
370f0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
37100 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e  tion must return
37110 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74   an.** integer t
37120 68 61 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c  hat is negative,
37130 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69   zero, or positi
37140 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72  ve.** if the fir
37150 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73  st string is les
37160 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f  s than, equal to
37170 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  , or greater tha
37180 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a  n the second,.**
37190 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20   respectively.  
371a0 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  A collating func
371b0 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73  tion must always
371c0 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
371d0 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e   answer.** given
371e0 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73   the same inputs
371f0 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  .  If two or mor
37200 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
37210 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74  tions are regist
37220 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73  ered.** to the s
37230 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61  ame collation na
37240 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66 65 72  me (using differ
37250 65 6e 74 20 65 54 65 78 74 52 65 70 20 76 61 6c  ent eTextRep val
37260 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a  ues) then all.**
37270 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65 71   must give an eq
37280 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20  uivalent answer 
37290 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74  when invoked wit
372a0 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72  h equivalent str
372b0 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c  ings..** The col
372c0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
372d0 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f  must obey the fo
372e0 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69  llowing properti
372f0 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74  es for all.** st
37300 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20  rings A, B, and 
37310 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  C:.**.** <ol>.**
37320 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68   <li> If A==B th
37330 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e  en B==A..** <li>
37340 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d   If A==B and B==
37350 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20  C then A==C..** 
37360 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54  <li> If A&lt;B T
37370 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c  HEN B&gt;A..** <
37380 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e  li> If A&lt;B an
37390 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26  d B&lt;C then A&
373a0 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  lt;C..** </ol>.*
373b0 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74  *.** If a collat
373c0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69  ing function fai
373d0 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62  ls any of the ab
373e0 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  ove constraints 
373f0 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c  and that.** coll
37400 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
37410 73 20 20 72 65 67 69 73 74 65 72 65 64 20 61 6e  s  registered an
37420 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65  d used, then the
37430 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
37440 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ite.** is undefi
37450 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
37460 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
37470 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f  ollation_v2() wo
37480 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
37490 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
374a0 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  n().** with the 
374b0 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68  addition that th
374c0 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62  e xDestroy callb
374d0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
374e0 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74  n pArg when.** t
374f0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
37500 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
37510 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20  ..** ^Collating 
37520 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65  functions are de
37530 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 79 20  leted when they 
37540 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62  are overridden b
37550 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73  y later.** calls
37560 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   to the collatio
37570 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74  n creation funct
37580 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65  ions or when the
37590 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
375a0 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f  nnection] is clo
375b0 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  sed using [sqlit
375c0 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  e3_close()]..**.
375d0 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79  ** ^The xDestroy
375e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e   callback is <u>
375f0 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69  not</u> called i
37600 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65  f the .** sqlite
37610 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
37620 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e  on_v2() function
37630 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61   fails.  Applica
37640 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b  tions that invok
37650 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  e.** sqlite3_cre
37660 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
37670 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  () with a non-NU
37680 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67 75  LL xDestroy argu
37690 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20  ment should .** 
376a0 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
376b0 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73   code and dispos
376c0 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
376d0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
376e0 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20  r.** themselves 
376f0 72 61 74 68 65 72 20 74 68 61 6e 20 65 78 70 65  rather than expe
37700 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20  cting SQLite to 
37710 64 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72  deal with it for
37720 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69   them..** This i
37730 73 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  s different from
37740 20 65 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c   every other SQL
37750 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
37760 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63  The inconsistenc
37770 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75  y .** is unfortu
37780 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20  nate but cannot 
37790 62 65 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f  be changed witho
377a0 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b  ut breaking back
377b0 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74  wards .** compat
377c0 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53  ibility..**.** S
377d0 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74  ee also:  [sqlit
377e0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
377f0 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ded()] and [sqli
37800 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
37810 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e  eded16()]..*/.in
37820 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
37830 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71  _collation(.  sq
37840 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
37850 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
37860 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
37870 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
37880 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
37890 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
378a0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
378b0 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
378c0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
378d0 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ation_v2(.  sqli
378e0 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
378f0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
37900 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
37910 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
37920 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
37930 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
37940 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
37950 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  d*),.  void(*xDe
37960 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
37970 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
37980 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
37990 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
379a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d  const void *zNam
379b0 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  e,.  int eTextRe
379c0 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67  p, .  void *pArg
379d0 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
379e0 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
379f0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
37a00 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
37a10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
37a20 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43  llation Needed C
37a30 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
37a40 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20  To avoid having 
37a50 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20  to register all 
37a60 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
37a70 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74  ces before a dat
37a80 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20  abase.** can be 
37a90 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63  used, a single c
37aa0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
37ab0 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72   may be register
37ac0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
37ad0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37ae0 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b  ion] to be invok
37af0 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75  ed whenever an u
37b00 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
37b10 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69  on.** sequence i
37b20 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  s required..**.*
37b30 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  * ^If the functi
37b40 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64  on is registered
37b50 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
37b60 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
37b70 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68  ded() API,.** th
37b80 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20  en it is passed 
37b90 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64  the names of und
37ba0 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
37bb0 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74   sequences as st
37bc0 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64  rings.** encoded
37bd0 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73   in UTF-8. ^If s
37be0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
37bf0 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75  _needed16() is u
37c00 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  sed,.** the name
37c10 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  s are passed as 
37c20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e  UTF-16 in machin
37c30 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
37c40 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  der..** ^A call 
37c50 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69  to either functi
37c60 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20  on replaces the 
37c70 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69  existing collati
37c80 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61  on-needed callba
37c90 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e  ck..**.** ^(When
37ca0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
37cb0 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69   invoked, the fi
37cc0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
37cd0 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a  sed is a copy.**
37ce0 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
37cf0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
37d00 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
37d10 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ded() or.** sqli
37d20 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
37d30 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73  eded16().  The s
37d40 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
37d50 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
37d60 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  * connection.  T
37d70 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
37d80 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
37d90 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
37da0 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
37db0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
37dc0 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  LE], indicating 
37dd0 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62  the most desirab
37de0 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63  le form of the c
37df0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
37e00 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65  ence function re
37e10 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75  quired.  The fou
37e20 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
37e30 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
37e40 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c  .** required col
37e50 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e  lation sequence.
37e60 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  )^.**.** The cal
37e70 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73  lback function s
37e80 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74  hould register t
37e90 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61  he desired colla
37ea0 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
37eb0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
37ec0 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c  llation()], [sql
37ed0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
37ee0 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  ation16()], or.*
37ef0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
37f00 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
37f10 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
37f20 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
37f30 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ed(.  sqlite3*, 
37f40 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69  .  void*, .  voi
37f50 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
37f60 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
37f70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b  ,const char*).);
37f80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
37f90 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
37fa0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
37fb0 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29  void*,.  void(*)
37fc0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
37fd0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
37fe0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69  st void*).);..#i
37ff0 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f  fdef SQLITE_HAS_
38000 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63  CODEC./*.** Spec
38010 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20  ify the key for 
38020 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74  an encrypted dat
38030 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75  abase.  This rou
38040 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  tine should be.*
38050 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61  * called right a
38060 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  fter sqlite3_ope
38070 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  n()..**.** The c
38080 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
38090 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
380a0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
380b0 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
380c0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
380d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65  /.int sqlite3_ke
380e0 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
380f0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
38100 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
38110 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
38120 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
38130 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
38140 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a    /* The key */.
38150 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b  );.int sqlite3_k
38160 65 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  ey_v2(.  sqlite3
38170 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
38180 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
38190 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
381a0 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  d */.  const cha
381b0 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20  r *zDbName,     
381c0 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
381d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 2a 2f   the database */
381e0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
381f0 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
38200 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a    /* The key */.
38210 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65  );../*.** Change
38220 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f   the key on an o
38230 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49  pen database.  I
38240 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  f the current da
38250 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a  tabase is not.**
38260 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73   encrypted, this
38270 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e   routine will en
38280 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e  crypt it.  If pN
38290 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30  ew==0 or nNew==0
382a0 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  , the.** databas
382b0 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a  e is decrypted..
382c0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
382d0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
382e0 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
382f0 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
38300 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
38310 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
38320 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a   sqlite3_rekey(.
38330 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
38340 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38350 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
38360 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
38370 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
38380 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
38390 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f  * The new key */
383a0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
383b0 72 65 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c 69  rekey_v2(.  sqli
383c0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
383d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
383e0 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
383f0 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
38400 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20  char *zDbName,  
38410 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
38420 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
38430 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
38440 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
38450 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20       /* The new 
38460 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
38470 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74   Specify the act
38480 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20  ivation key for 
38490 61 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20  a SEE database. 
384a0 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69   Unless .** acti
384b0 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74  vated, none of t
384c0 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20  he SEE routines 
384d0 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f  will work..*/.vo
384e0 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76  id sqlite3_activ
384f0 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74  ate_see(.  const
38500 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61   char *zPassPhra
38510 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74  se        /* Act
38520 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a  ivation phrase *
38530 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66  /.);.#endif..#if
38540 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c  def SQLITE_ENABL
38550 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70  E_CEROD./*.** Sp
38560 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61  ecify the activa
38570 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43  tion key for a C
38580 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20  EROD database.  
38590 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76  Unless .** activ
385a0 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68  ated, none of th
385b0 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73  e CEROD routines
385c0 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76   will work..*/.v
385d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69  oid sqlite3_acti
385e0 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f  vate_cerod(.  co
385f0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50  nst char *zPassP
38600 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20  hrase        /* 
38610 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73  Activation phras
38620 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a  e */.);.#endif..
38630 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
38640 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f  Suspend Executio
38650 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69  n For A Short Ti
38660 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  me.**.** The sql
38670 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e  ite3_sleep() fun
38680 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65  ction causes the
38690 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20   current thread 
386a0 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75  to suspend execu
386b0 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c  tion.** for at l
386c0 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66  east a number of
386d0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70   milliseconds sp
386e0 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70  ecified in its p
386f0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
38700 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  If the operating
38710 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74   system does not
38720 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72   support sleep r
38730 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20  equests with.** 
38740 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65  millisecond time
38750 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65   resolution, the
38760 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20  n the time will 
38770 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f  be rounded up to
38780 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20  .** the nearest 
38790 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62  second. The numb
387a0 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
387b0 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75  ds of sleep actu
387c0 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65  ally.** requeste
387d0 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61  d from the opera
387e0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72  ting system is r
387f0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
38800 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74  SQLite implement
38810 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  s this interface
38820 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20   by calling the 
38830 78 53 6c 65 65 7