/ Hex Artifact Content
Login

Artifact 58d18cf47b056ba56ed2c566c783026bc742ea2c:


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 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6220: 45 5f 4f 50 45 4e 5f 46 49 4c 45 50 52 4f 54 45  E_OPEN_FILEPROTE
6230: 43 54 49 4f 4e 5f 4d 41 53 4b 20 20 20 20 20 20  CTION_MASK      
6240: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6250: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 37             0x007
6260: 30 30 30 30 30 0a 0a 2f 2a 20 52 65 73 65 72 76  00000../* Reserv
6270: 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20  ed:             
6280: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6290: 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  F00000 */../*.**
62a0: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63   CAPI3REF: Devic
62b0: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63  e Characteristic
62c0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76  s.**.** The xDev
62d0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
62e0: 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  cs method of the
62f0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6300: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  hods].** object 
6310: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
6320: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65  er which is a ve
6330: 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a  ctor of these.**
6340: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
6350: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
6360: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
6370: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
6380: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
6390: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
63a0: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
63b0: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
63c0: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** 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 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
63f0: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
6400: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
6410: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
6420: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6430: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
6440: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
6450: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
6460: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
6470: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
6480: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
6490: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
64a0: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
64b0: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
64c0: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
64d0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
64e0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
64f0: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
6500: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
6510: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
6520: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
6530: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
6540: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
6550: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
6560: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
6570: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
6580: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
6590: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
65a0: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
65b0: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
65c0: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
65d0: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
65e0: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
65f0: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
6600: 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54  te().  The SQLIT
6610: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
6620: 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70  E_OVERWRITE prop
6630: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
6640: 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20  ** after reboot 
6650: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73  following a cras
6660: 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c  h or power loss,
6670: 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20   the only bytes 
6680: 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61  in a.** file tha
6690: 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61  t were written a
66a0: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
66b0: 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61  n level might ha
66c0: 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e  ve changed.** an
66d0: 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20  d that adjacent 
66e0: 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65  bytes, even byte
66f0: 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
6700: 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20  e sector are.** 
6710: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
6720: 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
6730: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6740: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6750: 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69  PEN.** flag indi
6760: 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c 65  cate that a file
6770: 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74   cannot be delet
6780: 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54  ed when open.  T
6790: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43  he.** SQLITE_IOC
67a0: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61  AP_IMMUTABLE fla
67b0: 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  g indicates that
67c0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a   the file is on.
67d0: 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64  ** read-only med
67e0: 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65  ia and cannot be
67f0: 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79   changed even by
6800: 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a   processes with.
6810: 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76  ** elevated priv
6820: 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69  ileges..*/.#defi
6830: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6840: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
6850: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6860: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6870: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
6880: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6890: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65  00000002.#define
68a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
68b0: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20  OMIC1K          
68c0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
68d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
68e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20  OCAP_ATOMIC2K   
68f0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6900: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
6910: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6920: 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC4K            
6930: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
6940: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6950: 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20  AP_ATOMIC8K     
6960: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6970: 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0020.#define SQL
6980: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6990: 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  16K             
69a0: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66   0x00000040.#def
69b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
69c0: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20  _ATOMIC32K      
69d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
69e0: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  80.#define SQLIT
69f0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
6a00: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6a10: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e  x00000100.#defin
6a20: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6a30: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20  AFE_APPEND      
6a40: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
6a50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6a60: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6a70: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6a80: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20  0000400.#define 
6a90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
6aa0: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
6ab0: 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23  EN  0x00000800.#
6ac0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6ad0: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
6ae0: 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30  ERWRITE    0x000
6af0: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
6b00: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
6b10: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  ABLE            
6b20: 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a    0x00002000../*
6b30: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
6b40: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c  le Locking Level
6b50: 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  s.**.** SQLite u
6b60: 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ses one of these
6b70: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6b80: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
6b90: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
6ba0: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74  ls it makes to t
6bb0: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  he xLock() and x
6bc0: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73  Unlock() methods
6bd0: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  .** of an [sqlit
6be0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6bf0: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
6c00: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f  e SQLITE_LOCK_NO
6c10: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  NE          0.#d
6c20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6c30: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20  K_SHARED        
6c40: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6c50: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20  _LOCK_RESERVED  
6c60: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
6c70: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6c80: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  G       3.#defin
6c90: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58  e SQLITE_LOCK_EX
6ca0: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f  CLUSIVE     4../
6cb0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
6cc0: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54  ynchronization T
6cd0: 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ype Flags.**.** 
6ce0: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
6cf0: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20  kes the xSync() 
6d00: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20  method of an.** 
6d10: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6d20: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75  ods] object it u
6d30: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f  ses a combinatio
6d40: 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e  n of.** these in
6d50: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
6d60: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
6d70: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ent..**.** When 
6d80: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
6d90: 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73  DATAONLY flag is
6da0: 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20   used, it means 
6db0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63  that the.** sync
6dc0: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20   operation only 
6dd0: 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64  needs to flush d
6de0: 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72  ata to mass stor
6df0: 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69  age.  Inode.** i
6e00: 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20  nformation need 
6e10: 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20  not be flushed. 
6e20: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
6e30: 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c  r bits of the fl
6e40: 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49  ag.** equal SQLI
6e50: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20  TE_SYNC_NORMAL, 
6e60: 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73  that means to us
6e70: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6e80: 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49   semantics..** I
6e90: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
6ea0: 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49   bits equal SQLI
6eb0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68  TE_SYNC_FULL, th
6ec0: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  at means.** to u
6ed0: 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c  se Mac OS X styl
6ee0: 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65  e fullsync inste
6ef0: 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a  ad of fsync()..*
6f00: 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66  *.** Do not conf
6f10: 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53  use the SQLITE_S
6f20: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6f30: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6f40: 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68  flags.** with th
6f50: 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  e [PRAGMA synchr
6f60: 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e  onous]=NORMAL an
6f70: 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  d [PRAGMA synchr
6f80: 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73  onous]=FULL.** s
6f90: 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73  ettings.  The [s
6fa0: 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d  ynchronous pragm
6fb0: 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68  a] determines wh
6fc0: 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a  en calls to the.
6fd0: 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74  ** xSync VFS met
6fe0: 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70  hod occur and ap
6ff0: 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20  plies uniformly 
7000: 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66  across all platf
7010: 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  orms..** The SQL
7020: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
7030: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
7040: 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72  FULL flags deter
7050: 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72  mine how.** ener
7060: 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75  getic or rigorou
7070: 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68  s or forceful th
7080: 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  e sync operation
7090: 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c  s are and.** onl
70a0: 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65  y make a differe
70b0: 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66  nce on Mac OSX f
70c0: 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53  or the default S
70d0: 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28  QLite code..** (
70e0: 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20  Third-party VFS 
70f0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7100: 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20  might also make 
7110: 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a  the distinction.
7120: 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54  ** between SQLIT
7130: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
7140: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
7150: 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68  LL, but among th
7160: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73  e.** operating s
7170: 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20  ystems natively 
7180: 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
7190: 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53  ite, only Mac OS
71a0: 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74  X.** cares about
71b0: 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e   the difference.
71c0: 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ).*/.#define SQL
71d0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
71e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23         0x00002.#
71f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
7200: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20  NC_FULL         
7210: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65   0x00003.#define
7220: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
7230: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30  AONLY      0x000
7240: 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
7250: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
7260: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c   Open File Handl
7270: 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69  e.**.** An [sqli
7280: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7290: 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
72a0: 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20  pen file in the 
72b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
72c0: 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20   | OS interface 
72d0: 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64  layer].  Individ
72e0: 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ual OS interface
72f0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
7300: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
7310: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
7320: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
7330: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
7340: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
7350: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
7360: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
7370: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
7380: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
7390: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
73a0: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
73b0: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
73c0: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
73d0: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
73e0: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
73f0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
7400: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
7410: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
7420: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
7430: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
7440: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7450: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
7460: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
7470: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
7480: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7490: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
74a0: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
74b0: 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45  s Object.**.** E
74c0: 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64  very file opened
74d0: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
74e0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
74f0: 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a  od populates an.
7500: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7510: 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f  ] object (or, mo
7520: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73  re commonly, a s
7530: 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a  ubclass of the.*
7540: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
7550: 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20   object) with a 
7560: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
7570: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
7580: 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  bject..** This o
7590: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
75a0: 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74  e methods used t
75b0: 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
75c0: 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  s operations.** 
75d0: 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e  against the open
75e0: 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65   file represente
75f0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
7600: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a  3_file] object..
7610: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71  **.** If the [sq
7620: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7630: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65   method sets the
7640: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
7650: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a  ethods element .
7660: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ** to a non-NULL
7670: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74   pointer, then t
7680: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  he sqlite3_io_me
7690: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74  thods.xClose met
76a0: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e  hod.** may be in
76b0: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68  voked even if th
76c0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
76d0: 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74  Open] reported t
76e0: 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20  hat it failed.  
76f0: 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20  The.** only way 
7700: 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c  to prevent a cal
7710: 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c  l to xClose foll
7720: 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b  owing a failed [
7730: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7740: 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65  n].** is for the
7750: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7760: 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20  pen] to set the 
7770: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
7780: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a  thods element.**
7790: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
77a0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
77b0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
77c0: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
77d0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
77e0: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
77f0: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
7800: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
7810: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
7820: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
7830: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
7840: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
7850: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
7860: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
7870: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
7880: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
7890: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
78a0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
78b0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
78c0: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
78d0: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
78e0: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
78f0: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
7900: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
7910: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
7920: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7930: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
7940: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7950: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
7960: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7970: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
7980: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7990: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
79a0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
79b0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
79c0: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
79d0: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
79e0: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
79f0: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
7a00: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
7a10: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
7a20: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
7a30: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
7a40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
7a50: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
7a60: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
7a70: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
7a80: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
7a90: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
7aa0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
7ab0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
7ac0: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
7ad0: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
7ae0: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
7af0: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
7b00: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
7b10: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
7b20: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
7b30: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
7b40: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
7b50: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7b60: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
7b70: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
7b80: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
7b90: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7ba0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
7bb0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
7bc0: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
7bd0: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
7be0: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
7bf0: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
7c00: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
7c10: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
7c20: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
7c30: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
7c40: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
7c50: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
7c60: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
7c70: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
7c80: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
7c90: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
7ca0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
7cb0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
7cc0: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
7cd0: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
7ce0: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
7cf0: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
7d00: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
7d10: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
7d20: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
7d30: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
7d40: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
7d50: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
7d60: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
7d70: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
7d80: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
7d90: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
7da0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
7db0: 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e  ..** A [file con
7dc0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c  trol opcodes | l
7dd0: 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20  ist of opcodes] 
7de0: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73  less than 100 is
7df0: 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41   available..** A
7e00: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
7e10: 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d   define a custom
7e20: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
7e30: 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20  thod should use 
7e40: 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74  opcodes.** great
7e50: 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61  er than 100 to a
7e60: 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20  void conflicts. 
7e70: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7e80: 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  ions should.** r
7e90: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  eturn [SQLITE_NO
7ea0: 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65  TFOUND] for file
7eb0: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
7ec0: 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
7ed0: 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a  t.** recognize..
7ee0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f  **.** The xSecto
7ef0: 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72  rSize() method r
7f00: 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f  eturns the secto
7f10: 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a  r size of the.**
7f20: 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64   device that und
7f30: 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e  erlies the file.
7f40: 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a    The sector siz
7f50: 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69  e is the.** mini
7f60: 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63  mum write that c
7f70: 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20  an be performed 
7f80: 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69  without disturbi
7f90: 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65  ng.** other byte
7fa0: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  s in the file.  
7fb0: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
7fc0: 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20  cteristics().** 
7fd0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
7fe0: 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63   bit vector desc
7ff0: 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73  ribing behaviors
8000: 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72   of the.** under
8010: 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a  lying device:.**
8020: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8030: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8040: 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  TOMIC].** <li> [
8050: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8060: 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC512].** <li> 
8070: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8080: 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC1K].** <li> 
8090: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
80a0: 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC2K].** <li> 
80b0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
80c0: 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC4K].** <li> 
80d0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
80e0: 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC8K].** <li> 
80f0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8100: 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC16K].** <li>
8110: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8120: 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC32K].** <li
8130: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8140: 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC64K].** <l
8150: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8160: 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a  _SAFE_APPEND].**
8170: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8180: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a  CAP_SEQUENTIAL].
8190: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** 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 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
81c0: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
81d0: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
81e0: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
81f0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8200: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
8210: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
8220: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
8230: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
8240: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
8250: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
8260: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
8270: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
8280: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
8290: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
82a0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
82b0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
82c0: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
82d0: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
82e0: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
82f0: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
8300: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
8310: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
8320: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
8330: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
8340: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
8350: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
8360: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
8370: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
8380: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
8390: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
83a0: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
83b0: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
83c0: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
83d0: 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78  te()..**.** If x
83e0: 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53  Read() returns S
83f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
8400: 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61  T_READ it must a
8410: 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74  lso fill.** in t
8420: 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f  he unread portio
8430: 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ns of the buffer
8440: 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20   with zeros.  A 
8450: 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c  VFS that.** fail
8460: 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  s to zero-fill s
8470: 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74  hort reads might
8480: 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20   seem to work.  
8490: 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c  However,.** fail
84a0: 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ure to zero-fill
84b0: 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c   short reads wil
84c0: 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61  l eventually lea
84d0: 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65  d to.** database
84e0: 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
84f0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
8500: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8510: 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  s sqlite3_io_met
8520: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
8530: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
8540: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
8550: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
8560: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8570: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29  ;.  int (*xRead)
8580: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8590: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
85a0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
85b0: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
85c0: 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66  Write)(sqlite3_f
85d0: 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ile*, const void
85e0: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
85f0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
8600: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e  );.  int (*xTrun
8610: 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  cate)(sqlite3_fi
8620: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
8630: 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20  64 size);.  int 
8640: 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
8650: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67  _file*, int flag
8660: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  s);.  int (*xFil
8670: 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  eSize)(sqlite3_f
8680: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8690: 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69  t64 *pSize);.  i
86a0: 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69  nt (*xLock)(sqli
86b0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
86c0: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b  .  int (*xUnlock
86d0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
86e0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
86f0: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
8700: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8710: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
8720: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f  .  int (*xFileCo
8730: 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66  ntrol)(sqlite3_f
8740: 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f  ile*, int op, vo
8750: 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74  id *pArg);.  int
8760: 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28   (*xSectorSize)(
8770: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8780: 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43    int (*xDeviceC
8790: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28  haracteristics)(
87a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
87b0: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
87c0: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
87d0: 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20   version 1 */.  
87e0: 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73  int (*xShmMap)(s
87f0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8800: 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c  t iPg, int pgsz,
8810: 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74   int, void volat
8820: 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  ile**);.  int (*
8830: 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65  xShmLock)(sqlite
8840: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66  3_file*, int off
8850: 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20  set, int n, int 
8860: 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28  flags);.  void (
8870: 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71  *xShmBarrier)(sq
8880: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8890: 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29  int (*xShmUnmap)
88a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
88b0: 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b  int deleteFlag);
88c0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
88d0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
88e0: 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20  r version 2 */. 
88f0: 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73   int (*xFetch)(s
8900: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8910: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8920: 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69  t, int iAmt, voi
8930: 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28  d **pp);.  int (
8940: 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74  *xUnfetch)(sqlit
8950: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8960: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76  3_int64 iOfst, v
8970: 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65  oid *p);.  /* Me
8980: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8990: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
89a0: 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69  n 3 */.  /* Addi
89b0: 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d  tional methods m
89c0: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
89d0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a  uture releases *
89e0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
89f0: 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46  3REF: Standard F
8a00: 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f  ile Control Opco
8a10: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
8a20: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
8a30: 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f  pcodes} {file co
8a40: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a  ntrol opcode}.**
8a50: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
8a60: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
8a70: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
8a80: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
8a90: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
8aa0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8ab0: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
8ac0: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
8ad0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
8ae0: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
8af0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8b00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
8b10: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
8b20: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
8b30: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
8b40: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
8b50: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
8b60: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
8b70: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
8b80: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
8b90: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
8ba0: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
8bb0: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
8bc0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
8bd0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
8be0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
8bf0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
8c00: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
8c10: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
8c20: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
8c30: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
8c40: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
8c50: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
8c60: 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e  sting and only n
8c70: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
8c80: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
8c90: 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69  _TEST.** is defi
8ca0: 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  ned..** <ul>.** 
8cb0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
8cc0: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a  TL_SIZE_HINT]].*
8cd0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
8ce0: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f  NTL_SIZE_HINT] o
8cf0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79  pcode is used by
8d00: 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20   SQLite to give 
8d10: 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72  the VFS.** layer
8d20: 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c   a hint of how l
8d30: 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73  arge the databas
8d40: 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77  e file will grow
8d50: 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68   to be during th
8d60: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61  e.** current tra
8d70: 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20  nsaction.  This 
8d80: 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72  hint is not guar
8d90: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63  anteed to be acc
8da0: 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20  urate but it.** 
8db0: 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20  is often close. 
8dc0: 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   The underlying 
8dd0: 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65  VFS might choose
8de0: 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20   to preallocate 
8df0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
8e00: 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20   space based on 
8e10: 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64  this hint in ord
8e20: 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65  er to help write
8e30: 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  s to the databas
8e40: 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61  e.** file run fa
8e50: 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ster..**.** <li>
8e60: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  [[SQLITE_FCNTL_C
8e70: 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  HUNK_SIZE]].** T
8e80: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8e90: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63  _CHUNK_SIZE] opc
8ea0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72  ode is used to r
8eb0: 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20  equest that the 
8ec0: 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61  VFS.** extends a
8ed0: 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65  nd truncates the
8ee0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
8ef0: 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69  n chunks of a si
8f00: 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ze specified.** 
8f10: 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65  by the user. The
8f20: 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
8f30: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   to [sqlite3_fil
8f40: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f  e_control()] sho
8f50: 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  uld .** point to
8f60: 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70   an integer (typ
8f70: 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e  e int) containin
8f80: 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d  g the new chunk-
8f90: 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66  size to use.** f
8fa0: 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64  or the nominated
8fb0: 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63   database. Alloc
8fc0: 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66  ating database f
8fd0: 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72  ile space in lar
8fe0: 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61  ge.** chunks (sa
8ff0: 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29  y 1MB at a time)
9000: 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c  , may reduce fil
9010: 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e  e-system fragmen
9020: 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d  tation and.** im
9030: 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
9040: 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d  e on some system
9050: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
9060: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
9070: 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68  _POINTER]].** Th
9080: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9090: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70  FILE_POINTER] op
90a0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
90b0: 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72  obtain a pointer
90c0: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
90d0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
90e0: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
90f0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
9100: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
9110: 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b  tion.  See the [
9120: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9130: 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74  trol()] document
9140: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64  ation for.** add
9150: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
9160: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ion..**.** <li>[
9170: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
9180: 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20  NC_OMITTED]].** 
9190: 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65  No longer in use
91a0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
91b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d  LITE_FCNTL_SYNC]
91c0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
91d0: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63  _FCNTL_SYNC] opc
91e0: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
91f0: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53   internally by S
9200: 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e  QLite and.** sen
9210: 74 20 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d  t to the VFS imm
9220: 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20  ediately before 
9230: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
9240: 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61   is invoked on a
9250: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c  .** database fil
9260: 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72  e descriptor. Or
9270: 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d  , if the xSync m
9280: 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76  ethod is not inv
9290: 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65  oked .** because
92a0: 20 74 68 65 20 75 73 65 72 20 68 61 73 20 63 6f   the user has co
92b0: 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74 65 20  nfigured SQLite 
92c0: 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41  with .** [PRAGMA
92d0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50   synchronous | P
92e0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
92f0: 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76  s=OFF] it is inv
9300: 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a  oked in place .*
9310: 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d  * of the xSync m
9320: 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63  ethod. In most c
9330: 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65  ases, the pointe
9340: 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  r argument passe
9350: 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66  d with.** this f
9360: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e  ile-control is N
9370: 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66  ULL. However, if
9380: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
9390: 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63  le is being sync
93a0: 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66  ed.** as part of
93b0: 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73   a multi-databas
93c0: 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72  e commit, the ar
93d0: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f  gument points to
93e0: 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65   a nul-terminate
93f0: 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  d.** string cont
9400: 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73  aining the trans
9410: 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a  actions master-j
9420: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65  ournal file name
9430: 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a  . VFSes that .**
9440: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69   do not need thi
9450: 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20  s signal should 
9460: 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20  silently ignore 
9470: 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70  this opcode. App
9480: 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68  lications .** sh
9490: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73  ould not call [s
94a0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
94b0: 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73  rol()] with this
94c0: 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67   opcode as doing
94d0: 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72   so may .** disr
94e0: 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f  upt the operatio
94f0: 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c  n of the special
9500: 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20  ized VFSes that 
9510: 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20  do require it.  
9520: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9530: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
9540: 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54  _PHASETWO]].** T
9550: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9560: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
9570: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65  ] opcode is gene
9580: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  rated internally
9590: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
95a0: 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46  d sent to the VF
95b0: 53 20 61 66 74 65 72 20 61 20 74 72 61 6e 73 61  S after a transa
95c0: 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63  ction has been c
95d0: 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61  ommitted immedia
95e0: 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f  tely.** but befo
95f0: 72 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  re the database 
9600: 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53  is unlocked. VFS
9610: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e  es that do not n
9620: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a  eed this signal.
9630: 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  ** should silent
9640: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
9650: 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69  pcode. Applicati
9660: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ons should not c
9670: 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
9680: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9690: 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65  with this opcode
96a0: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
96b0: 20 64 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a   disrupt the .**
96c0: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68   operation of th
96d0: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
96e0: 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75  Ses that do requ
96f0: 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20  ire it.  .**.** 
9700: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9710: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
9720: 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  Y]].** ^The [SQL
9730: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
9740: 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65  AV_RETRY] opcode
9750: 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66   is used to conf
9760: 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a  igure automatic.
9770: 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20  ** retry counts 
9780: 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f  and intervals fo
9790: 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49  r certain disk I
97a0: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f  /O operations fo
97b0: 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73  r the.** windows
97c0: 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20   [VFS] in order 
97d0: 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73  to provide robus
97e0: 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72 65  tness in the pre
97f0: 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69  sence of.** anti
9800: 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e  -virus programs.
9810: 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68    By default, th
9820: 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69  e windows VFS wi
9830: 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72 65  ll retry file re
9840: 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74  ad,.** file writ
9850: 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65  e, and file dele
9860: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70  te operations up
9870: 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69   to 10 times, wi
9880: 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66  th a delay.** of
9890: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
98a0: 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72 73   before the firs
98b0: 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74 68  t retry and with
98c0: 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65   the delay incre
98d0: 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61  asing.** by an a
98e0: 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c  dditional 25 mil
98f0: 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65  liseconds with e
9900: 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 72  ach subsequent r
9910: 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  etry.  This.** o
9920: 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65  pcode allows the
9930: 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31  se two values (1
9940: 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32 35  0 retries and 25
9950: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
9960: 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65   delay).** to be
9970: 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20   adjusted.  The 
9980: 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67  values are chang
9990: 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62  ed for all datab
99a0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  ase connections.
99b0: 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  ** within the sa
99c0: 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65  me process.  The
99d0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
99e0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72  ointer to an arr
99f0: 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74  ay of two.** int
9a00: 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65 20  egers where the 
9a10: 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69 20  first integer i 
9a20: 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f  the new retry co
9a30: 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  unt and the seco
9a40: 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73  nd.** integer is
9a50: 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20   the delay.  If 
9a60: 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69  either integer i
9a70: 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
9a80: 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20   the setting.** 
9a90: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62  is not changed b
9aa0: 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70  ut instead the p
9ab0: 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
9ac0: 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72  at setting is wr
9ad0: 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68  itten.** into th
9ae0: 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61  e array entry, a
9af0: 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72  llowing the curr
9b00: 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e  ent retry settin
9b10: 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65  gs to be.** inte
9b20: 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a  rrogated.  The z
9b30: 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  DbName parameter
9b40: 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
9b50: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9b60: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
9b70: 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  L]].** ^The [SQL
9b80: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
9b90: 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73  T_WAL] opcode is
9ba0: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
9bb0: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72  query the.** per
9bc0: 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57  sistent [WAL | W
9bd0: 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20  rite Ahead Log] 
9be0: 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66  setting.  By def
9bf0: 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69  ault, the auxili
9c00: 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65  ary.** write ahe
9c10: 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65  ad log and share
9c20: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75  d memory files u
9c30: 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74  sed for transact
9c40: 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61  ion control.** a
9c50: 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
9c60: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68   deleted when th
9c70: 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74  e latest connect
9c80: 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62  ion to the datab
9c90: 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20  ase.** closes.  
9ca0: 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65  Setting persiste
9cb0: 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73  nt WAL mode caus
9cc0: 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74  es those files t
9cd0: 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a  o persist after.
9ce0: 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69  ** close.  Persi
9cf0: 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20  sting the files 
9d00: 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f  is useful when o
9d10: 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74  ther processes t
9d20: 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61  hat do not.** ha
9d30: 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73  ve write permiss
9d40: 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63  ion on the direc
9d50: 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20  tory containing 
9d60: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
9d70: 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61  e want.** to rea
9d80: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  d the database f
9d90: 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20  ile, as the WAL 
9da0: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72  and shared memor
9db0: 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69  y files must exi
9dc0: 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66  st.** in order f
9dd0: 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
9de0: 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20  to be readable. 
9df0: 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
9e00: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
9e10: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9e20: 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70  l()] for this op
9e30: 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61  code should be a
9e40: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
9e50: 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20  nteger..** That 
9e60: 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20  integer is 0 to 
9e70: 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65  disable persiste
9e80: 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31  nt WAL mode or 1
9e90: 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69   to enable persi
9ea0: 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64  stent.** WAL mod
9eb0: 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67  e.  If the integ
9ec0: 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69  er is -1, then i
9ed0: 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  t is overwritten
9ee0: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
9ef0: 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74  t.** WAL persist
9f00: 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  ence setting..**
9f10: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9f20: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
9f30: 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20  _OVERWRITE]].** 
9f40: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
9f50: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
9f60: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
9f70: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
9f80: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
9f90: 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73  rsistent "powers
9fa0: 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f  afe-overwrite" o
9fb0: 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67  r "PSOW" setting
9fc0: 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74 74  .  The PSOW sett
9fd0: 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65  ing.** determine
9fe0: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f  s the [SQLITE_IO
9ff0: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
a000: 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20  ERWRITE] bit of 
a010: 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68  the.** xDeviceCh
a020: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
a030: 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74  thods. The fourt
a040: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
a050: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
a060: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74  control()] for t
a070: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c  his opcode shoul
a080: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  d be a pointer t
a090: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  o an integer..**
a0a0: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73   That integer is
a0b0: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65   0 to disable ze
a0c0: 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f  ro-damage mode o
a0d0: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65  r 1 to enable ze
a0e0: 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64  ro-damage.** mod
a0f0: 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67  e.  If the integ
a100: 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69  er is -1, then i
a110: 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  t is overwritten
a120: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
a130: 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65  t.** zero-damage
a140: 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a   mode setting..*
a150: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a160: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
a170: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
a180: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a190: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  ITE] opcode is i
a1a0: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
a1b0: 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a   after opening.*
a1c0: 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61  * a write transa
a1d0: 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74  ction to indicat
a1e0: 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69  e that, unless i
a1f0: 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t is rolled back
a200: 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61   for some.** rea
a210: 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20  son, the entire 
a220: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
a230: 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ll be overwritte
a240: 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74  n by the current
a250: 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e   .** transaction
a260: 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62  . This is used b
a270: 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69  y VACUUM operati
a280: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ons..**.** <li>[
a290: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a2a0: 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  SNAME]].** ^The 
a2b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a2c0: 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61  SNAME] opcode ca
a2d0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
a2e0: 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
a2f0: 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20  .** all [VFSes] 
a300: 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b  in the VFS stack
a310: 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65  .  The names are
a320: 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d   of all VFS shim
a330: 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e  s and the.** fin
a340: 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20  al bottom-level 
a350: 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20  VFS are written 
a360: 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
a370: 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  ined from .** [s
a380: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
a390: 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20   and the result 
a3a0: 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65  is stored in the
a3b0: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a   char* variable.
a3c0: 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72  ** that the four
a3d0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  th parameter of 
a3e0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a3f0: 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20  ntrol()] points 
a400: 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65  to..** The calle
a410: 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  r is responsible
a420: 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65   for freeing the
a430: 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e   memory when don
a440: 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61  e.  As with.** a
a450: 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ll file-control 
a460: 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69  actions, there i
a470: 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74  s no guarantee t
a480: 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63  hat this will ac
a490: 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79  tually.** do any
a4a0: 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20  thing.  Callers 
a4b0: 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a  should initializ
a4c0: 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69  e the char* vari
a4d0: 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a  able to a NULL.*
a4e0: 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73  * pointer in cas
a4f0: 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74  e this file-cont
a500: 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65  rol is not imple
a510: 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69  mented.  This fi
a520: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73  le-control.** is
a530: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69   intended for di
a540: 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c  agnostic use onl
a550: 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  y..**.** <li>[[S
a560: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a570: 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65  MA]].** ^Wheneve
a580: 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  r a [PRAGMA] sta
a590: 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64  tement is parsed
a5a0: 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e  , an [SQLITE_FCN
a5b0: 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66  TL_PRAGMA] .** f
a5c0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73  ile control is s
a5d0: 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20  ent to the open 
a5e0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
a5f0: 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64  bject correspond
a600: 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61  ing.** to the da
a610: 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77  tabase file to w
a620: 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20  hich the pragma 
a630: 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73  statement refers
a640: 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a  . ^The argument.
a650: 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54  ** to the [SQLIT
a660: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a670: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
a680: 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70  an array of.** p
a690: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
a6a0: 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77  gs (char**) in w
a6b0: 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20  hich the second 
a6c0: 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  element of the a
a6d0: 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e  rray.** is the n
a6e0: 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ame of the pragm
a6f0: 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20  a and the third 
a700: 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61  element is the a
a710: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a  rgument to the.*
a720: 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c  * pragma or NULL
a730: 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68   if the pragma h
a740: 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20  as no argument. 
a750: 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f   ^The handler fo
a760: 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  r an.** [SQLITE_
a770: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
a780: 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f  le control can o
a790: 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74  ptionally make t
a7a0: 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74  he first element
a7b0: 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a  .** of the char*
a7c0: 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  * argument point
a7d0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74   to a string obt
a7e0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
a7f0: 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a  te3_mprintf()].*
a800: 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c  * or the equival
a810: 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72  ent and that str
a820: 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20  ing will become 
a830: 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68  the result of th
a840: 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74  e pragma or.** t
a850: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
a860: 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66   if the pragma f
a870: 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a  ails. ^If the.**
a880: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a890: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
a8a0: 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  rol returns [SQL
a8b0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74  ITE_NOTFOUND], t
a8c0: 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b  hen normal .** [
a8d0: 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69  PRAGMA] processi
a8e0: 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e  ng continues.  ^
a8f0: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
a900: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
a910: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
a920: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
a930: 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65  , then the parse
a940: 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  r assumes that t
a950: 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61  he.** VFS has ha
a960: 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41  ndled the PRAGMA
a970: 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20   itself and the 
a980: 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73  parser generates
a990: 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70   a no-op.** prep
a9a0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20  ared statement. 
a9b0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
a9c0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
a9d0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
a9e0: 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c  rns.** any resul
a9f0: 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61  t code other tha
aa00: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  n [SQLITE_OK] or
aa10: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
aa20: 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a  D], that means.*
aa30: 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65  * that the VFS e
aa40: 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72  ncountered an er
aa50: 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69  ror while handli
aa60: 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20  ng the [PRAGMA] 
aa70: 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  and the.** compi
aa80: 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52  lation of the PR
aa90: 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20  AGMA fails with 
aaa0: 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20  an error.  ^The 
aab0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
aac0: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
aad0: 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20  ntrol occurs at 
aae0: 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
aaf0: 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e   pragma statemen
ab00: 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73  t analysis and s
ab10: 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20  o.** it is able 
ab20: 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c  to override buil
ab30: 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74  t-in [PRAGMA] st
ab40: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
ab50: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
ab60: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d  TL_BUSYHANDLER]]
ab70: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
ab80: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
ab90: 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74  ER].** file-cont
aba0: 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  rol may be invok
abb0: 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20  ed by SQLite on 
abc0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
abd0: 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72  e handle.** shor
abe0: 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20  tly after it is 
abf0: 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20  opened in order 
ac00: 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73  to provide a cus
ac10: 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63  tom VFS with acc
ac20: 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  ess.** to the co
ac30: 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68  nnections busy-h
ac40: 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  andler callback.
ac50: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
ac60: 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a   of type (void *
ac70: 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79  *).** - an array
ac80: 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29   of two (void *)
ac90: 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72   values. The fir
aca0: 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75  st (void *) actu
acb0: 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74  ally points.** t
acc0: 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
acd0: 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f  type (int (*)(vo
ace0: 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72  id *)). In order
acf0: 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63   to invoke the c
ad00: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75  onnections.** bu
ad10: 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73  sy-handler, this
ad20: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
ad30: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
ad40: 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69   the second (voi
ad50: 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61  d *) in.** the a
ad60: 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79  rray as the only
ad70: 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74   argument. If it
ad80: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
ad90: 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72  o, then the oper
ada0: 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
adb0: 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69  be retried. If i
adc0: 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  t returns zero, 
add0: 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73  the custom VFS s
ade0: 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68  hould abandon th
adf0: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65  e.** current ope
ae00: 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ration..**.** <l
ae10: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ae20: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a  _TEMPFILENAME]].
ae30: 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20  ** ^Application 
ae40: 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b  can invoke the [
ae50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
ae60: 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d  PFILENAME] file-
ae70: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61  control.** to ha
ae80: 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61  ve SQLite genera
ae90: 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  te a.** temporar
aea0: 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67  y filename using
aeb0: 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
aec0: 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c  thm that is foll
aed0: 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65  owed to generate
aee0: 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
aef0: 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50  lenames for TEMP
af00: 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65   tables and othe
af10: 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e  r internal uses.
af20: 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e    The.** argumen
af30: 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68  t should be a ch
af40: 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20  ar** which will 
af50: 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  be filled with t
af60: 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77  he filename.** w
af70: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
af80: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
af90: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
afa0: 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72  ()].  The caller
afb0: 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b   should.** invok
afc0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
afd0: 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74  )] on the result
afe0: 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f   to avoid a memo
aff0: 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c  ry leak..**.** <
b000: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b010: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  L_MMAP_SIZE]].**
b020: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b030: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
b040: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le control is us
b050: 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73  ed to query or s
b060: 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75  et the.** maximu
b070: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
b080: 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75  s that will be u
b090: 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d  sed for memory-m
b0a0: 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68  apped I/O..** Th
b0b0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
b0c0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
b0d0: 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74  ue of type sqlit
b0e0: 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a  e3_int64 that.**
b0f0: 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20   is an advisory 
b100: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
b110: 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  f bytes in the f
b120: 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61  ile to memory ma
b130: 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74  p.  The.** point
b140: 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  er is overwritte
b150: 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76  n with the old v
b160: 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74  alue.  The limit
b170: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
b180: 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  if.** the value 
b190: 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74  originally point
b1a0: 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76  ed to is negativ
b1b0: 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75  e, and so the cu
b1c0: 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20  rrent limit .** 
b1d0: 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62  can be queried b
b1e0: 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70  y passing in a p
b1f0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61  ointer to a nega
b200: 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68  tive number.  Th
b210: 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  is.** file-contr
b220: 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  ol is used inter
b230: 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65  nally to impleme
b240: 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  nt [PRAGMA mmap_
b250: 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  size]..**.** <li
b260: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b270: 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  TRACE]].** The [
b280: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
b290: 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  CE] file control
b2a0: 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f   provides adviso
b2b0: 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ry information.*
b2c0: 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f  * to the VFS abo
b2d0: 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68  ut what the high
b2e0: 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65  er layers of the
b2f0: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72   SQLite stack ar
b300: 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73  e doing..** This
b310: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
b320: 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46   used by some VF
b330: 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69  S activity traci
b340: 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54  ng [shims]..** T
b350: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
b360: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
b370: 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72   string.  Higher
b380: 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a   layers in the.*
b390: 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d  * SQLite stack m
b3a0: 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74  ay generate inst
b3b0: 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69  ances of this fi
b3c0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a  le control if.**
b3d0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
b3e0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f  _FCNTL_TRACE] co
b3f0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
b400: 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
b410: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b420: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
b430: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b440: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
b450: 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  D] file control 
b460: 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61  interprets its a
b470: 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20  rgument as a.** 
b480: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
b490: 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69  teger and it wri
b4a0: 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e  tes a boolean in
b4b0: 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20  to that integer 
b4c0: 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20  depending.** on 
b4d0: 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
b4e0: 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e  he file has been
b4f0: 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c   renamed, moved,
b500: 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63   or deleted sinc
b510: 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73  e it.** was firs
b520: 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  t opened..**.** 
b530: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b540: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
b550: 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  DLE]].** The [SQ
b560: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
b570: 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63  _SET_HANDLE] opc
b580: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
b590: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
b5a0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
b5b0: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
b5c0: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61  ol method to swa
b5d0: 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c  p the file handl
b5e0: 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a  e with the one.*
b5f0: 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
b600: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
b610: 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c  t.  This capabil
b620: 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69  ity is used duri
b630: 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e  ng testing.** an
b640: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
b650: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
b660: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73  n SQLITE_TEST is
b670: 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
b680: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </ul>.*/.#define
b690: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
b6a0: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20  CKSTATE         
b6b0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
b6c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54  SQLITE_FCNTL_GET
b6d0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
b6e0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
b6f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
b700: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
b710: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
b720: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
b730: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
b740: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
b750: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
b760: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  INT             
b770: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
b780: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
b790: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
b7a0: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
b7b0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
b7c0: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
b7d0: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
b7e0: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
b7f0: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38  TED            8
b800: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b810: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
b820: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a  ETRY          9.
b830: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b840: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
b850: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
b860: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b870: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20  NTL_OVERWRITE   
b880: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64             11.#d
b890: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b8a0: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20  TL_VFSNAME      
b8b0: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65            12.#de
b8c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b8d0: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
b8e0: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66  WRITE    13.#def
b8f0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b900: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
b910: 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69          14.#defi
b920: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b930: 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20  BUSYHANDLER     
b940: 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e         15.#defin
b950: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
b960: 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20  EMPFILENAME     
b970: 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65        16.#define
b980: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d   SQLITE_FCNTL_MM
b990: 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  AP_SIZE         
b9a0: 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20       18.#define 
b9b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
b9c0: 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CE              
b9d0: 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53      19.#define S
b9e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
b9f0: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20  MOVED           
ba00: 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51     20.#define SQ
ba10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20  LITE_FCNTL_SYNC 
ba20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
ba30: 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    21.#define SQL
ba40: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
ba50: 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20  _PHASETWO       
ba60: 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   22.#define SQLI
ba70: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
ba80: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
ba90: 32 33 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64  23./* deprecated
baa0: 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e   names */.#defin
bab0: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43  e SQLITE_GET_LOC
bac0: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
bad0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54  SQLITE_FCNTL_GET
bae0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23  _LOCKPROXYFILE.#
baf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
bb00: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
bb10: 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54       SQLITE_FCNT
bb20: 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_SET_LOCKPROXYF
bb30: 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  ILE.#define SQLI
bb40: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
bb50: 20 20 20 20 20 20 20 20 20 20 53 51 4c 49 54 45            SQLITE
bb60: 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e  _FCNTL_LAST_ERRN
bb70: 4f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  O../*.** CAPI3RE
bb80: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a  F: Mutex Handle.
bb90: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
bba0: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
bbb0: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
bbc0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
bbd0: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
bbe0: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
bbf0: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
bc00: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
bc10: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
bc20: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
bc30: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
bc40: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
bc50: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
bc60: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
bc70: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
bc80: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
bc90: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
bca0: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
bcb0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
bcc0: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
bcd0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
bce0: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
bcf0: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
bd00: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
bd10: 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a  rface Object.**.
bd20: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
bd30: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
bd40: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
bd50: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
bd60: 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51  etween.** the SQ
bd70: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68  Lite core and th
bd80: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
bd90: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
bda0: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20  The "vfs".** in 
bdb0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
bdc0: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f  object stands fo
bdd0: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20  r "virtual file 
bde0: 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a  system".  See.**
bdf0: 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20   the [VFS | VFS 
be00: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
be10: 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72  or further infor
be20: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
be30: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69  e value of the i
be40: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73  Version field is
be50: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74   initially 1 but
be60: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69   may be larger i
be70: 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73  n.** future vers
be80: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ions of SQLite. 
be90: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   Additional fiel
bea0: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
beb0: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62  ed to this.** ob
bec0: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56  ject when the iV
bed0: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20  ersion value is 
bee0: 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65  increased.  Note
bef0: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
bf00: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
bf10: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
bf20: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
bf30: 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77  transaction betw
bf40: 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  een.** SQLite ve
bf50: 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20  rsion 3.5.9 and 
bf60: 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68  3.6.0 and yet th
bf70: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
bf80: 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69   was not.** modi
bf90: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fied..**.** The 
bfa0: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
bfb0: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
bfc0: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
bfd0: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
bfe0: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
bff0: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
c000: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
c010: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
c020: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
c030: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
c040: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69   Registered sqli
c050: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20  te3_vfs objects 
c060: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
c070: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
c080: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
c090: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
c0a0: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
c0b0: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
c0c0: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
c0d0: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
c0e0: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
c0f0: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
c100: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
c110: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
c120: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
c130: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
c140: 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65  he list.  Neithe
c150: 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
c160: 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56  n code nor the V
c170: 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  FS.** implementa
c180: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20  tion should use 
c190: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
c1a0: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65  r..**.** The pNe
c1b0: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  xt field is the 
c1c0: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68  only field in th
c1d0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
c1e0: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
c1f0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72  SQLite will ever
c200: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65   modify.  SQLite
c210: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73   will only acces
c220: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74  s.** or modify t
c230: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20  his field while 
c240: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63  holding a partic
c250: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65  ular static mute
c260: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  x..** The applic
c270: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
c280: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69  er modify anythi
c290: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71  ng within the sq
c2a0: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a  lite3_vfs.** obj
c2b0: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a  ect once the obj
c2c0: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67  ect has been reg
c2d0: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  istered..**.** T
c2e0: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68  he zName field h
c2f0: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  olds the name of
c300: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e   the VFS module.
c310: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a    The name must.
c320: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72  ** be unique acr
c330: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75  oss all VFS modu
c340: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  les..**.** [[sql
c350: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d  ite3_vfs.xOpen]]
c360: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
c370: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
c380: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
c390: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20  ter to xOpen.** 
c3a0: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  is either a NULL
c3b0: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69   pointer or stri
c3c0: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ng obtained.** f
c3d0: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  rom xFullPathnam
c3e0: 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69  e() with an opti
c3f0: 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65  onal suffix adde
c400: 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66  d..** ^If a suff
c410: 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74  ix is added to t
c420: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
c430: 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a  ameter, it will.
c440: 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20  ** consist of a 
c450: 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61  single "-" chara
c460: 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79  cter followed by
c470: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a   no more than.**
c480: 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   11 alphanumeric
c490: 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72   and/or "-" char
c4a0: 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69  acters..** ^SQLi
c4b0: 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61  te further guara
c4c0: 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  ntees that.** th
c4d0: 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
c4e0: 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61   valid and uncha
c4f0: 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73  nged until xClos
c500: 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  e() is.** called
c510: 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65  . Because of the
c520: 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
c530: 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ce,.** the [sqli
c540: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61  te3_file] can sa
c550: 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69  fely store a poi
c560: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66  nter to the.** f
c570: 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65  ilename if it ne
c580: 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  eds to remember 
c590: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72  the filename for
c5a0: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a   some reason..**
c5b0: 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   If the zFilenam
c5c0: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
c5d0: 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70  Open is a NULL p
c5e0: 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65  ointer then xOpe
c5f0: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74  n.** must invent
c600: 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61   its own tempora
c610: 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20  ry name for the 
c620: 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72  file.  ^Whenever
c630: 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61   the .** xFilena
c640: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
c650: 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73  NULL it will als
c660: 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  o be the case th
c670: 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20  at the.** flags 
c680: 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69  parameter will i
c690: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
c6a0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
c6b0: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  E]..**.** The fl
c6c0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
c6d0: 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73  xOpen() includes
c6e0: 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e   all bits set in
c6f0: 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72  .** the flags ar
c700: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
c710: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20  e3_open_v2()].  
c720: 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f  Or if [sqlite3_o
c730: 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  pen()].** or [sq
c740: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
c750: 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c  is used, then fl
c760: 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20  ags includes at 
c770: 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45  least.** [SQLITE
c780: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
c790: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
c7a0: 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20  CREATE]. .** If 
c7b0: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20  xOpen() opens a 
c7c0: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74  file read-only t
c7d0: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75  hen it sets *pOu
c7e0: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63  tFlags to.** inc
c7f0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
c800: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74  N_READONLY].  Ot
c810: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75  her bits in *pOu
c820: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65  tFlags may be se
c830: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74  t..**.** ^(SQLit
c840: 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20  e will also add 
c850: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
c860: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
c870: 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c  e xOpen().** cal
c880: 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  l, depending on 
c890: 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67  the object being
c8a0: 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c   opened:.**.** <
c8b0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ul>.** <li>  [SQ
c8c0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
c8d0: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
c8e0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
c8f0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
c900: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
c910: 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  P_DB].** <li>  [
c920: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
c930: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
c940: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
c950: 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a  TRANSIENT_DB].**
c960: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c970: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a  PEN_SUBJOURNAL].
c980: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
c990: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
c9a0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
c9b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d  SQLITE_OPEN_WAL]
c9c0: 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
c9d0: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69  * The file I/O i
c9e0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61  mplementation ca
c9f0: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74  n use the object
ca00: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a   type flags to.*
ca10: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79  * change the way
ca20: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66   it deals with f
ca30: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  iles.  For examp
ca40: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
ca50: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  on.** that does 
ca60: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63  not care about c
ca70: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72  rash recovery or
ca80: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   rollback might 
ca90: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e  make.** the open
caa0: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69   of a journal fi
cab0: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69  le a no-op.  Wri
cac0: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72  tes to this jour
cad0: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73  nal would.** als
cae0: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64  o be no-ops, and
caf0: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   any attempt to 
cb00: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
cb10: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a   would return.**
cb20: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20   SQLITE_IOERR.  
cb30: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  Or the implement
cb40: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f  ation might reco
cb50: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74  gnize that a dat
cb60: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69  abase.** file wi
cb70: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65  ll be doing page
cb80: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20  -aligned sector 
cb90: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73  reads and writes
cba0: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20   in a random.** 
cbb0: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70  order and set up
cbc0: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
cbd0: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
cbe0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67  **.** SQLite mig
cbf0: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ht also add one 
cc00: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
cc10: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
cc20: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  pen method:.**.*
cc30: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
cc40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
cc50: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c  TEONCLOSE].** <l
cc60: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
cc70: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f  EXCLUSIVE].** </
cc80: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ul>.**.** The [S
cc90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
cca0: 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d  EONCLOSE] flag m
ccb0: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
ccc0: 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74  ould be.** delet
ccd0: 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c  ed when it is cl
cce0: 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c  osed.  ^The [SQL
ccf0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
cd00: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20  NCLOSE].** will 
cd10: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20  be set for TEMP 
cd20: 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68  databases and th
cd30: 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72  eir journals, tr
cd40: 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62  ansient.** datab
cd50: 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75  ases, and subjou
cd60: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rnals..**.** ^Th
cd70: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
cd80: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69  XCLUSIVE] flag i
cd90: 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e  s always used in
cda0: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20   conjunction.** 
cdb0: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
cdc0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c  _OPEN_CREATE] fl
cdd0: 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f  ag, which are bo
cde0: 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61  th directly.** a
cdf0: 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20  nalogous to the 
ce00: 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45  O_EXCL and O_CRE
ce10: 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20  AT flags of the 
ce20: 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20  POSIX open().** 
ce30: 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45  API.  The SQLITE
ce40: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
ce50: 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65  flag, when paire
ce60: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
ce70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
ce80: 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e  E, is used to in
ce90: 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65  dicate that file
cea0: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a   should always.*
ceb0: 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e  * be created, an
cec0: 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20  d that it is an 
ced0: 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65  error if it alre
cee0: 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49  ady exists..** I
cef0: 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20  t is <i>not</i> 
cf00: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
cf10: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
cf20: 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66   be opened .** f
cf30: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
cf40: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c  ess..**.** ^At l
cf50: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79  east szOsFile by
cf60: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72  tes of memory ar
cf70: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
cf80: 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64  QLite.** to hold
cf90: 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66   the  [sqlite3_f
cfa0: 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70  ile] structure p
cfb0: 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
cfc0: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  rd.** argument t
cfd0: 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f  o xOpen.  The xO
cfe0: 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20  pen method does 
cff0: 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61  not have to.** a
d000: 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75  llocate the stru
d010: 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64  cture; it should
d020: 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e   just fill it in
d030: 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20  .  Note that.** 
d040: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
d050: 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71   must set the sq
d060: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
d070: 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a  ods to either.**
d080: 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65   a valid [sqlite
d090: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
d0a0: 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e  ject or to NULL.
d0b0: 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a    xOpen must do.
d0c0: 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20  ** this even if 
d0d0: 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20  the open fails. 
d0e0: 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20   SQLite expects 
d0f0: 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33  that the sqlite3
d100: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a  _file.pMethods.*
d110: 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62  * element will b
d120: 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f  e valid after xO
d130: 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61  pen returns rega
d140: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75  rdless of the su
d150: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c  ccess.** or fail
d160: 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e  ure of the xOpen
d170: 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73   call..**.** [[s
d180: 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65  qlite3_vfs.xAcce
d190: 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61  ss]].** ^The fla
d1a0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
d1b0: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
d1c0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
d1d0: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
d1e0: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
d1f0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
d200: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
d210: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
d220: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
d230: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
d240: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
d250: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
d260: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
d270: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
d280: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
d290: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
d2a0: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
d2b0: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
d2c0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77  ^SQLite will alw
d2d0: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
d2e0: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
d2f0: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
d300: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
d310: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
d320: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
d330: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
d340: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
d350: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
d360: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
d370: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
d380: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
d390: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
d3a0: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
d3b0: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
d3c0: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
d3d0: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
d3e0: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
d3f0: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
d400: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
d410: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
d420: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
d430: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
d440: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
d450: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
d460: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
d470: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
d480: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
d490: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20  xCurrentTime(), 
d4a0: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
d4b0: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72  Int64().** inter
d4c0: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74  faces are not st
d4d0: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
d4e0: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
d4f0: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
d500: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
d510: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
d520: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
d530: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
d540: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
d550: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
d560: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
d570: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
d580: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
d590: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
d5a0: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
d5b0: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
d5c0: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
d5d0: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
d5e0: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
d5f0: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
d600: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
d610: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
d620: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
d630: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
d640: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
d650: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
d660: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
d670: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
d680: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
d690: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
d6a0: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20  nd time as.** a 
d6b0: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
d6c0: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43  alue..** ^The xC
d6d0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
d6e0: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
d6f0: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c  , as an integer,
d700: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44   the Julian.** D
d710: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70  ay Number multip
d720: 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30  lied by 86400000
d730: 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   (the number of 
d740: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20  milliseconds in 
d750: 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61  .** a 24-hour da
d760: 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65  y).  .** ^SQLite
d770: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43   will use the xC
d780: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
d790: 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20  ) method to get 
d7a0: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64  the current.** d
d7b0: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20  ate and time if 
d7c0: 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61  that method is a
d7d0: 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65  vailable (if iVe
d7e0: 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a  rsion is 2 or .*
d7f0: 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68  * greater and th
d800: 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
d810: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20  er is not NULL) 
d820: 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61  and will fall ba
d830: 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e  ck.** to xCurren
d840: 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72  tTime() if xCurr
d850: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69  entTimeInt64() i
d860: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
d870: 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79  *.** ^The xSetSy
d880: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74  stemCall(), xGet
d890: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e  SystemCall(), an
d8a0: 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c  d xNestSystemCal
d8b0: 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  l() interfaces.*
d8c0: 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62  * are not used b
d8d0: 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  y the SQLite cor
d8e0: 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  e.  These option
d8f0: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
d900: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79  e provided.** by
d910: 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66   some VFSes to f
d920: 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e  acilitate testin
d930: 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64  g of the VFS cod
d940: 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67  e. By overriding
d950: 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c   .** system call
d960: 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73  s with functions
d970: 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72   under its contr
d980: 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72  ol, a test progr
d990: 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61  am can.** simula
d9a0: 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72  te faults and er
d9b0: 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74  ror conditions t
d9c0: 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77  hat would otherw
d9d0: 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74  ise be difficult
d9e0: 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c  .** or impossibl
d9f0: 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68  e to induce.  Th
da00: 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20  e set of system 
da10: 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62  calls that can b
da20: 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20  e overridden.** 
da30: 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20  varies from one 
da40: 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20  VFS to another, 
da50: 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72  and from one ver
da60: 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65  sion of the same
da70: 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e   VFS to the.** n
da80: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
da90: 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73  ns that use thes
daa0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73  e interfaces mus
dab0: 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f  t be prepared fo
dac0: 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20  r any.** or all 
dad0: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  of these interfa
dae0: 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f  ces to be NULL o
daf0: 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61  r for their beha
db00: 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a  vior to change.*
db10: 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61  * from one relea
db20: 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20  se to the next. 
db30: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75   Applications mu
db40: 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74  st not attempt t
db50: 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20  o access.** any 
db60: 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73  of these methods
db70: 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   if the iVersion
db80: 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c   of the VFS is l
db90: 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74  ess than 3..*/.t
dba0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
dbb0: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
dbc0: 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76  3_vfs;.typedef v
dbd0: 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79  oid (*sqlite3_sy
dbe0: 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29  scall_ptr)(void)
dbf0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
dc00: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
dc10: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
dc20: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
dc30: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63  ersion number (c
dc40: 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20  urrently 3) */. 
dc50: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
dc60: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
dc70: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
dc80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
dc90: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
dca0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
dcb0: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
dcc0: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
dcd0: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
dce0: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
dcf0: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
dd00: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
dd10: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
dd20: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
dd30: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
dd40: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
dd50: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
dd60: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
dd70: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
dd80: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
dd90: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
dda0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
ddb0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
ddc0: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
ddd0: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
dde0: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
ddf0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
de00: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
de10: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
de20: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
de30: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
de40: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
de50: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
de60: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
de70: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
de80: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
de90: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
dea0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
deb0: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
dec0: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
ded0: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
dee0: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
def0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
df00: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
df10: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
df20: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
df30: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
df40: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a  sg);.  void (*(*
df50: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
df60: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
df70: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
df80: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20  )(void);.  void 
df90: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
dfa0: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
dfb0: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
dfc0: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
dfd0: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
dfe0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
dff0: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
e000: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
e010: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
e020: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
e030: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
e040: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e  , double*);.  in
e050: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f  t (*xGetLastErro
e060: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
e070: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20   int, char *);. 
e080: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
e090: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
e0a0: 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74  n version 1 of t
e0b0: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
e0c0: 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69  ject.  ** defini
e0d0: 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61  tion.  Those tha
e0e0: 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64  t follow are add
e0f0: 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20  ed in version 2 
e100: 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20  or later.  */.  
e110: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
e120: 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33  meInt64)(sqlite3
e130: 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69  _vfs*, sqlite3_i
e140: 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  nt64*);.  /*.  *
e150: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
e160: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
e170: 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74  ons 1 and 2 of t
e180: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
e190: 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65  ject..  ** Those
e1a0: 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76   below are for v
e1b0: 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65  ersion 3 and gre
e1c0: 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74  ater..  */.  int
e1d0: 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c   (*xSetSystemCal
e1e0: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
e1f0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
e200: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63  me, sqlite3_sysc
e210: 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69  all_ptr);.  sqli
e220: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20  te3_syscall_ptr 
e230: 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xGetSystemCall
e240: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e250: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e260: 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  e);.  const char
e270: 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43   *(*xNextSystemC
e280: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
e290: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e2a0: 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  Name);.  /*.  **
e2b0: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
e2c0: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
e2d0: 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f  ns 1 through 3 o
e2e0: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
e2f0: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65   object..  ** Ne
e300: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
e310: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75  appended in figu
e320: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
e330: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
e340: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
e350: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
e360: 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a  is happens. .  *
e370: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
e380: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
e390: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20  the xAccess VFS 
e3a0: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
e3b0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
e3c0: 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64  ants can be used
e3d0: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61   as the third pa
e3e0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
e3f0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
e400: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
e410: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  vfs] object.  Th
e420: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  ey determine.** 
e430: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72  what kind of per
e440: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63  missions the xAc
e450: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c  cess method is l
e460: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57  ooking for..** W
e470: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
e480: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41  S_EXISTS, the xA
e490: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
e4a0: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68  simply checks wh
e4b0: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65  ether the file e
e4c0: 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53  xists..** With S
e4d0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
e4e0: 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63  DWRITE, the xAcc
e4f0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
e500: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
e510: 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79   named directory
e520: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
e530: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a  e and writable.*
e540: 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  * (in other word
e550: 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20  s, if files can 
e560: 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65  be added, remove
e570: 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77  d, and renamed w
e580: 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72  ithin.** the dir
e590: 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20  ectory)..** The 
e5a0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
e5b0: 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74  ADWRITE constant
e5c0: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73   is currently us
e5d0: 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a  ed only by the.*
e5e0: 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  * [temp_store_di
e5f0: 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c  rectory pragma],
e600: 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75   though this cou
e610: 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ld change in a f
e620: 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
e630: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57   of SQLite..** W
e640: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
e650: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63  S_READ, the xAcc
e660: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
e670: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
e680: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
e690: 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41  e.  The SQLITE_A
e6a0: 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74  CCESS_READ const
e6b0: 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e  ant is.** curren
e6c0: 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75  tly unused, thou
e6d0: 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75  gh it might be u
e6e0: 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20  sed in a future 
e6f0: 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
e700: 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
e710: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
e720: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
e730: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
e740: 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f  _READWRITE 1   /
e750: 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41  * Used by PRAGMA
e760: 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65   temp_store_dire
e770: 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ctory */.#define
e780: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
e790: 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20  EAD      2   /* 
e7a0: 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  Unused */../*.**
e7b0: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
e7c0: 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63   for the xShmLoc
e7d0: 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  k VFS method.**.
e7e0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
e7f0: 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
e800: 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f  e the various lo
e810: 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73  cking operations
e820: 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74  .** allowed by t
e830: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
e840: 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69  od of [sqlite3_i
e850: 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65  o_methods].  The
e860: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72  .** following ar
e870: 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c  e the only legal
e880: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66   combinations of
e890: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a   flags to the.**
e8a0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
e8b0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
e8c0: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
e8d0: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
e8e0: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
e8f0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
e900: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
e910: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69  EXCLUSIVE.** <li
e920: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
e930: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
e940: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
e950: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
e960: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
e970: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f  _EXCLUSIVE.** </
e980: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75  ul>.**.** When u
e990: 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61  nlocking, the sa
e9a0: 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43  me SHARED or EXC
e9b0: 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74  LUSIVE flag must
e9c0: 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a   be supplied as.
e9d0: 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20  ** was given on 
e9e0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
e9f0: 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20  g lock.  .**.** 
ea00: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
ea10: 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69  hod can transiti
ea20: 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  on between unloc
ea30: 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f  ked and SHARED o
ea40: 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c  r.** between unl
ea50: 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53  ocked and EXCLUS
ea60: 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20  IVE.  It cannot 
ea70: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
ea80: 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64  en SHARED.** and
ea90: 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23   EXCLUSIVE..*/.#
eaa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
eab0: 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31  M_UNLOCK       1
eac0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ead0: 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  SHM_LOCK        
eae0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
eaf0: 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20  E_SHM_SHARED    
eb00: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
eb10: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
eb20: 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41  E    8../*.** CA
eb30: 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20  PI3REF: Maximum 
eb40: 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a  xShmLock index.*
eb50: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
eb60: 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c  k method on [sql
eb70: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
eb80: 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a   may use values.
eb90: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ** between 0 and
eba0: 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e   this upper boun
ebb0: 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74  d as its "offset
ebc0: 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  " argument..** T
ebd0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77  he SQLite core w
ebe0: 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70  ill never attemp
ebf0: 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20  t to acquire or 
ec00: 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63  release a.** loc
ec10: 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69  k outside of thi
ec20: 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69  s range.*/.#defi
ec30: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c  ne SQLITE_SHM_NL
ec40: 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f  OCK        8.../
ec50: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
ec60: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
ec70: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
ec80: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
ec90: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
eca0: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  tine initializes
ecb0: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c   the.** SQLite l
ecc0: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71  ibrary.  ^The sq
ecd0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
ece0: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
ecf0: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
ed00: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
ed10: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
ed20: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ed30: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  )..** These rout
ed40: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65  ines are designe
ed50: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63  d to aid in proc
ed60: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
ed70: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f  on and.** shutdo
ed80: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73  wn on embedded s
ed90: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61  ystems.  Worksta
eda0: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tion application
edb0: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74  s using.** SQLit
edc0: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f  e normally do no
edd0: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65  t need to invoke
ede0: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
edf0: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
ee00: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
ee10: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
ee20: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
ee30: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
ee40: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
ee50: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
ee60: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
ee70: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
ee80: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
ee90: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
eea0: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
eeb0: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
eec0: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
eed0: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
eee0: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
eef0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
ef00: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74  ^(Only an effect
ef10: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
ef20: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ef30: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
ef40: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
ef50: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
ef60: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
ef70: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  -ops.)^.**.** A 
ef80: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
ef90: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e  shutdown() is an
efa0: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
efb0: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  l if it is the f
efc0: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  irst.** call to 
efd0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
efe0: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73  () since the las
eff0: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
f000: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a  lize().  ^(Only.
f010: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
f020: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
f030: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
f040: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
f050: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
f060: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74  er valid calls t
f070: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
f080: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
f090: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
f0a0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
f0b0: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72  itialize() inter
f0c0: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61  face is threadsa
f0d0: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f  fe, but sqlite3_
f0e0: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73  shutdown().** is
f0f0: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74   not.  The sqlit
f100: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e  e3_shutdown() in
f110: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c  terface must onl
f120: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  y be called from
f130: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72   a.** single thr
f140: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b  ead.  All open [
f150: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f160: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c  ions] must be cl
f170: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20  osed and all.** 
f180: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73  other SQLite res
f190: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64  ources must be d
f1a0: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72  eallocated prior
f1b0: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   to invoking.** 
f1c0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f1d0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ()..**.** Among 
f1e0: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73  other things, ^s
f1f0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f200: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
f210: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
f220: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
f230: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64  , ^sqlite3_shutd
f240: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e  own().** will in
f250: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
f260: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  end()..**.** ^Th
f270: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
f280: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
f290: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
f2a0: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
f2b0: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  * ^If for some r
f2c0: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
f2d0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
f2e0: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
f2f0: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
f300: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
f310: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
f320: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
f330: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
f340: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
f350: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
f360: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
f370: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
f380: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
f390: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
f3a0: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
f3b0: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
f3c0: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
f3d0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
f3e0: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
f3f0: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
f400: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
f410: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
f420: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
f430: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
f440: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
f450: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
f460: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f470: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
f480: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
f490: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
f4a0: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
f4b0: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
f4c0: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
f4d0: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
f4e0: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
f4f0: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65  lready.  ^Howeve
f500: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
f510: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
f520: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
f530: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
f540: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
f550: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
f560: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
f570: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f580: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
f590: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
f5a0: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
f5b0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f5c0: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
f5d0: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
f5e0: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
f5f0: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
f600: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
f610: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
f620: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
f630: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
f640: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
f650: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
f660: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
f670: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
f680: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
f690: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
f6a0: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
f6b0: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
f6c0: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
f6d0: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
f6e0: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
f6f0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
f700: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
f710: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
f720: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
f730: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
f740: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
f750: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
f760: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
f770: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
f780: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
f790: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
f7a0: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
f7b0: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
f7c0: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
f7d0: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
f7e0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
f7f0: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
f800: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
f810: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
f820: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
f830: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
f840: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
f850: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
f860: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
f870: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
f880: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
f890: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
f8a0: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
f8b0: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
f8c0: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
f8d0: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
f8e0: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
f8f0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
f900: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
f910: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
f920: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
f930: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
f940: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
f950: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
f960: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
f970: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
f980: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
f990: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
f9a0: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
f9b0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
f9c0: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
f9d0: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
f9e0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
f9f0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
fa00: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
fa10: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
fa20: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
fa30: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
fa40: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
fa50: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fa60: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
fa70: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
fa80: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
fa90: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
faa0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
fab0: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
fac0: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
fad0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
fae0: 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f  Unix, Windows, o
faf0: 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r OS/2..** When 
fb00: 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c  [custom builds |
fb10: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
fb20: 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28   platforms].** (
fb30: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
fb40: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
fb50: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
fb60: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
fb70: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
fb80: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
fb90: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
fba0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
fbb0: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
fbc0: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
fbd0: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
fbe0: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
fbf0: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
fc00: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
fc10: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
fc20: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
fc30: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
fc40: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
fc50: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
fc60: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
fc70: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
fc80: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
fc90: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  );.int sqlite3_s
fca0: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69  hutdown(void);.i
fcb0: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
fcc0: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  it(void);.int sq
fcd0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
fce0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
fcf0: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
fd00: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
fd10: 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
fd20: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
fd30: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
fd40: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
fd50: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
fd60: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
fd70: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
fd80: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
fd90: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
fda0: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
fdb0: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
fdc0: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
fdd0: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
fde0: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
fdf0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
fe00: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
fe10: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
fe20: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
fe30: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
fe40: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
fe50: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
fe60: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
fe70: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
fe80: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
fe90: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
fea0: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
feb0: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
fec0: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
fed0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
fee0: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
fef0: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
ff00: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
ff10: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
ff20: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
ff30: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
ff40: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
ff50: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
ff60: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
ff70: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
ff80: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
ff90: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
ffa0: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
ffb0: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
ffc0: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
ffd0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ffe0: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
fff0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
10000 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
10010 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
10020 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
10030 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
10040 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
10050 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
10060 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
10070 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
10080 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
10090 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
100a0 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
100b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
100c0 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
100d0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
100e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
100f0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10100 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
10110 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  ** [configuratio
10120 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64  n option] that d
10130 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61  etermines.** wha
10140 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51  t property of SQ
10150 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f  Lite is to be co
10160 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65  nfigured.  Subse
10170 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a  quent arguments.
10180 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ** vary dependin
10190 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67  g on the [config
101a0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
101b0 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
101c0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
101d0 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72  ^When a configur
101e0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
101f0 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
10200 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
10210 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49  QLITE_OK]..** ^I
10220 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
10230 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
10240 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
10250 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
10260 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
10270 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
10280 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
10290 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
102a0 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
102b0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
102c0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
102d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
102e0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ions.**.** The s
102f0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
10300 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
10310 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
10320 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
10330 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
10340 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10350 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
10360 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
10370 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
10380 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
10390 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
103a0 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
103b0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
103c0 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
103d0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
103e0 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a  argument)..**.**
103f0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
10400 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
10410 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
10420 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53  .)  is the.** [S
10430 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
10440 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69  OOKASIDE | confi
10450 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d  guration verb] -
10460 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
10470 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
10480 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20  tes what aspect 
10490 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
104a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
104b0 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
104c0 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20  ..** Subsequent 
104d0 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64  arguments vary d
104e0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
104f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
10500 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73  rb..**.** ^Calls
10510 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
10520 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53  onfig() return S
10530 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20  QLITE_OK if and 
10540 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63  only if.** the c
10550 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65  all is considere
10560 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f  d successful..*/
10570 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f  .int sqlite3_db_
10580 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
10590 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
105a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
105b0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
105c0 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
105d0 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
105e0 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
105f0 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
10600 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
10610 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
10620 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
10630 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
10640 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
10650 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
10660 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
10670 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
10680 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
10690 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
106a0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
106b0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
106c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
106d0 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
106e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
106f0 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
10700 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
10710 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
10720 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20  FIG_GETMALLOC]. 
10730 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67   .** By creating
10740 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
10750 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
10760 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
10770 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10780 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
10790 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72  _MALLOC]).** dur
107a0 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
107b0 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  n, an applicatio
107c0 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
107d0 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
107e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
107f0 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20  n subsystem for 
10800 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
10810 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20  r all of its.** 
10820 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
10830 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
10840 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
10850 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20  es with several 
10860 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79  [built-in memory
10870 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20   allocators].** 
10880 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74  that are perfect
10890 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
108a0 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
108b0 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
108c0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
108d0 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
108e0 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
108f0 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
10900 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
10910 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
10920 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
10930 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
10940 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
10950 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
10960 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
10970 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
10980 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
10990 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
109a0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
109b0 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
109c0 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
109d0 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
109e0 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
109f0 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
10a00 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
10a10 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
10a20 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
10a30 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
10a40 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20  lloc, xRealloc, 
10a50 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64  and xFree method
10a60 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
10a70 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
10a80 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
10a90 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
10aa0 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
10ab0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
10ac0 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
10ad0 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63  ees that the sec
10ae0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
10af0 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61  ** xRealloc is a
10b00 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65  lways a value re
10b10 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f  turned by a prio
10b20 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64  r call to xRound
10b30 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  up..**.** xSize 
10b40 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
10b50 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
10b60 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
10b70 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
10b80 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
10b90 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
10ba0 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
10bb0 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
10bc0 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
10bd0 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
10be0 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
10bf0 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
10c00 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
10c10 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
10c20 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
10c30 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
10c40 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
10c50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10c60 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
10c70 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
10c80 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
10c90 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
10ca0 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
10cb0 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
10cc0 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
10cd0 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
10ce0 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
10cf0 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
10d00 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
10d10 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
10d20 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
10d30 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
10d40 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
10d50 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
10d60 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
10d70 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
10d80 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
10d90 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
10da0 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
10db0 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
10dc0 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
10dd0 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
10de0 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
10df0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
10e00 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
10e10 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
10e20 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65  llocator.  For e
10e30 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69  xample,.** it mi
10e40 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79  ght allocate any
10e50 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73   require mutexes
10e60 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69   or initialize i
10e70 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20  nternal data.** 
10e80 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65  structures.  The
10e90 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
10ea0 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e  d is invoked (in
10eb0 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20  directly) by.** 
10ec0 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
10ed0 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20  n()] and should 
10ee0 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  deallocate any r
10ef0 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65  esources acquire
10f00 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20  d.** by xInit.  
10f10 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69  The pAppData poi
10f20 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20  nter is used as 
10f30 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
10f40 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61  er to.** xInit a
10f50 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a  nd xShutdown..**
10f60 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73  .** SQLite holds
10f70 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
10f80 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52  EX_STATIC_MASTER
10f90 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20  ] mutex when it 
10fa0 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78  invokes.** the x
10fb0 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20  Init method, so 
10fc0 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
10fd0 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72   need not be thr
10fe0 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a  eadsafe.  The.**
10ff0 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
11000 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64  d is only called
11010 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73   from [sqlite3_s
11020 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74  hutdown()] so it
11030 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65   does.** not nee
11040 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61  d to be threadsa
11050 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20  fe either.  For 
11060 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64  all other method
11070 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c  s, SQLite.** hol
11080 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
11090 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d  UTEX_STATIC_MEM]
110a0 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61   mutex as long a
110b0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
110c0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
110d0 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  S] configuration
110e0 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65   option is turne
110f0 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69  d on (which.** i
11100 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29  t is by default)
11110 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68   and so the meth
11120 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69  ods are automati
11130 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64  cally serialized
11140 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66  ..** However, if
11150 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
11160 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69  MEMSTATUS] is di
11170 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65  sabled, then the
11180 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64   other.** method
11190 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  s must be thread
111a0 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b  safe or else mak
111b0 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61  e their own arra
111c0 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20  ngements for.** 
111d0 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  serialization..*
111e0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  *.** SQLite will
111f0 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49   never invoke xI
11200 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20  nit() more than 
11210 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20  once without an 
11220 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63  intervening.** c
11230 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e  all to xShutdown
11240 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ()..*/.typedef s
11250 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
11260 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  m_methods sqlite
11270 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73  3_mem_methods;.s
11280 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
11290 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f  m_methods {.  vo
112a0 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69  id *(*xMalloc)(i
112b0 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20  nt);         /* 
112c0 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
112d0 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  n function */.  
112e0 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f  void (*xFree)(vo
112f0 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f  id*);          /
11300 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61  * Free a prior a
11310 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76  llocation */.  v
11320 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29  oid *(*xRealloc)
11330 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a  (void*,int);  /*
11340 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63   Resize an alloc
11350 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
11360 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20  *xSize)(void*); 
11370 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74            /* Ret
11380 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  urn the size of 
11390 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
113a0 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75  .  int (*xRoundu
113b0 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  p)(int);        
113c0 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65    /* Round up re
113d0 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c  quest size to al
113e0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f  location size */
113f0 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28  .  int (*xInit)(
11400 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
11410 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20    /* Initialize 
11420 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
11430 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28  ator */.  void (
11440 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64  *xShutdown)(void
11450 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e  *);      /* Dein
11460 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
11470 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
11480 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
11490 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  a;              
114a0 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f    /* Argument to
114b0 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68   xInit() and xSh
114c0 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a  utdown() */.};..
114d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
114e0 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
114f0 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
11500 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f  S: {configuratio
11510 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20  n option}.**.** 
11520 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
11530 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
11540 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
11550 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
11560 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
11570 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
11580 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
11590 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
115a0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
115b0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
115c0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
115d0 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
115e0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
115f0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
11600 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
11610 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
11620 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
11630 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
11640 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
11650 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
11660 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
11670 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
11680 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
11690 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
116a0 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    The [sqlite3_c
116b0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
116c0 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
116d0 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
116e0 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
116f0 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
11700 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
11710 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
11720 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
11730 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
11740 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
11750 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  GLETHREAD]] <dt>
11760 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
11770 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a  NGLETHREAD</dt>.
11780 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
11790 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
117a0 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
117b0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
117c0 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
117d0 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67  ng mode] to Sing
117e0 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  le-thread.  In o
117f0 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
11800 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  isables.** all m
11810 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73  utexing and puts
11820 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d   SQLite into a m
11830 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e  ode where it can
11840 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a   only be used.**
11850 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
11860 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ead.   ^If SQLit
11870 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11880 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
11890 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
118a0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
118b0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
118c0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
118d0 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
118e0 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  le to change the
118f0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11900 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75  ] from its defau
11910 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53  lt.** value of S
11920 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64  ingle-thread and
11930 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   so [sqlite3_con
11940 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
11950 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  rn .** [SQLITE_E
11960 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
11970 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
11980 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
11990 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  EAD.** configura
119a0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
119b0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
119c0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
119d0 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAD]] <dt>SQLITE
119e0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
119f0 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
11a00 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
11a10 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
11a20 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
11a30 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
11a40 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11a50 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61  ] to Multi-threa
11a60 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
11a70 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
11a80 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b  ** mutexing on [
11a90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11aa0 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
11ab0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
11ac0 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70  jects..** The ap
11ad0 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73  plication is res
11ae0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72  ponsible for ser
11af0 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20  ializing access 
11b00 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  to.** [database 
11b10 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
11b20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11b30 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68  ments].  But oth
11b40 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  er mutexes.** ar
11b50 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61  e enabled so tha
11b60 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  t SQLite will be
11b70 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20   safe to use in 
11b80 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
11b90 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20  .** environment 
11ba0 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77  as long as no tw
11bb0 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70  o threads attemp
11bc0 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  t to use the sam
11bd0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
11be0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68  onnection] at th
11bf0 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49  e same time.  ^I
11c00 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
11c10 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
11c20 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
11c30 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
11c40 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
11c50 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
11c60 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
11c70 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
11c80 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61   the Multi-threa
11c90 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
11ca0 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
11cb0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
11cc0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
11cd0 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
11ce0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
11cf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
11d00 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72  ITHREAD configur
11d10 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
11d20 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11d30 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
11d40 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  ZED]] <dt>SQLITE
11d50 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
11d60 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
11d70 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
11d80 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
11d90 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
11da0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
11db0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11dc0 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20   to Serialized. 
11dd0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
11de0 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62  this option enab
11df0 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
11e00 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65  es including the
11e10 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75   recursive.** mu
11e20 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61  texes on [databa
11e30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
11e40 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
11e50 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
11e60 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65  .** In this mode
11e70 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64   (which is the d
11e80 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69  efault when SQLi
11e90 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11ea0 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  ith.** [SQLITE_T
11eb0 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68  HREADSAFE=1]) th
11ec0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
11ed0 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72   will itself ser
11ee0 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a  ialize access.**
11ef0 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f   to [database co
11f00 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
11f10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
11f20 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65  nts] so that the
11f30 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
11f40 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74  is free to use t
11f50 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
11f60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72  e connection] or
11f70 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72   the.** same [pr
11f80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
11f90 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74  ] in different t
11fa0 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
11fb0 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20  me time..** ^If 
11fc0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11fd0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
11fe0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11ff0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
12000 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
12010 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
12020 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
12030 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
12040 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74  he Serialized [t
12050 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
12060 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
12070 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
12080 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
12090 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
120a0 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
120b0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
120c0 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ED configuration
120d0 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
120e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
120f0 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  FIG_MALLOC]] <dt
12100 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
12110 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
12120 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
12130 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70  CONFIG_MALLOC op
12140 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
12150 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
12160 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  ch is .** a poin
12170 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
12180 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
12190 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
121a0 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
121b0 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
121c0 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
121d0 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  ive low-level me
121e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
121f0 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
12200 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a  sed in place of.
12210 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ** the memory al
12220 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
12230 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
12240 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d  ite.)^ ^SQLite m
12250 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20  akes.** its own 
12260 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
12270 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
12280 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
12290 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
122a0 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65  re.** before the
122b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
122c0 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  ()] call returns
122d0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
122e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
122f0 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
12300 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
12310 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
12320 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
12330 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
12340 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
12350 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
12360 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
12370 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
12380 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
12390 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
123a0 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54   structure..** T
123b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
123c0 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
123d0 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
123e0 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
123f0 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72  ly defined memor
12400 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
12410 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
12420 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
12430 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
12440 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  the default memo
12450 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
12460 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
12470 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69   wrapper that si
12480 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79  mulations memory
12490 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
124a0 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73  ure or.** tracks
124b0 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66   memory usage, f
124c0 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64  or example. </dd
124d0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
124e0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
124f0 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  S]] <dt>SQLITE_C
12500 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c  ONFIG_MEMSTATUS<
12510 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
12520 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12530 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e  MEMSTATUS option
12540 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
12550 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
12560 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  nt,.** interpret
12570 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c  ed as a boolean,
12580 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
12590 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
125a0 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20  ollection of.** 
125b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
125c0 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28  n statistics. ^(
125d0 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  When memory allo
125e0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
125f0 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
12600 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  d, the following
12610 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
12620 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70  es become non-op
12630 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20  erational:.**   
12640 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  <ul>.**   <li> [
12650 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
12660 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  sed()].**   <li>
12670 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
12680 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a  _highwater()].**
12690 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
126a0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
126b0 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  64()].**   <li> 
126c0 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28  [sqlite3_status(
126d0 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a  )].**   </ul>)^.
126e0 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ** ^Memory alloc
126f0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
12700 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
12710 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53  default unless S
12720 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
12730 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
12740 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
12750 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20  TUS]=0 in which 
12760 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  case memory.** a
12770 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
12780 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
12790 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
127a0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
127b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
127c0 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATCH]] <dt>SQLIT
127d0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
127e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
127f0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
12800 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20  _SCRATCH option 
12810 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
12820 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
12830 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
12840 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61  can use for scra
12850 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54  tch memory.  ^(T
12860 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
12870 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53  rguments.** to S
12880 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
12890 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72  ATCH:  A pointer
128a0 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c   an 8-byte.** al
128b0 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66  igned memory buf
128c0 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74  fer from which t
128d0 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  he scratch alloc
128e0 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a  ations will be.*
128f0 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a  * drawn, the siz
12900 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63  e of each scratc
12910 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a  h allocation (sz
12920 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61  ),.** and the ma
12930 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
12940 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
12950 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68  ons (N).)^.** Th
12960 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
12970 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74   must be a point
12980 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
12990 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a  aligned buffer.*
129a0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  * of at least sz
129b0 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
129c0 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
129d0 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65  ill not use more
129e0 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63   than one scratc
129f0 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68  h buffers per th
12a00 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  read..** ^SQLite
12a10 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75   will never requ
12a20 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62 75  est a scratch bu
12a30 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72  ffer that is mor
12a40 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65  e than 6.** time
12a50 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  s the database p
12a60 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  age size..** ^If
12a70 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65   SQLite needs ne
12a80 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  eds additional.*
12a90 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
12aa0 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
12ab0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
12ac0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12ad0 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20  ption, then .** 
12ae0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
12af0 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  )] will be used 
12b00 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65  to obtain the me
12b10 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a  mory needed.<p>.
12b20 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70  ** ^When the app
12b30 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65  lication provide
12b40 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20  s any amount of 
12b50 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75  scratch memory u
12b60 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43  sing.** SQLITE_C
12b70 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53  ONFIG_SCRATCH, S
12b80 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e  QLite avoids unn
12b90 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a  ecessary large.*
12ba0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
12bb0 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f  c|heap allocatio
12bc0 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e  ns]..** This can
12bd0 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72   help [Robson pr
12be0 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f  oof|prevent memo
12bf0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
12c00 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68  ilures] due to h
12c10 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61  eap.** fragmenta
12c20 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f  tion in low-memo
12c30 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  ry embedded syst
12c40 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ems..** </dd>.**
12c50 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12c60 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20  FIG_PAGECACHE]] 
12c70 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12c80 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
12c90 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
12ca0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
12cb0 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65  CACHE option spe
12cc0 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
12cd0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a  memory buffer.**
12ce0 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
12cf0 20 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74   use for the dat
12d00 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65  abase page cache
12d10 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c   with the defaul
12d20 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  t page.** cache 
12d30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
12d40 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67   .** This config
12d50 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  uration should n
12d60 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e  ot be used if an
12d70 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
12d80 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ine page.** cach
12d90 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
12da0 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67   is loaded using
12db0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
12dc0 46 49 47 5f 50 43 41 43 48 45 32 5d 0a 2a 2a 20  FIG_PCACHE2].** 
12dd0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12de0 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 72 65 20  tion..** ^There 
12df0 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
12e00 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  nts to SQLITE_CO
12e10 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20  NFIG_PAGECACHE: 
12e20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  A pointer to.** 
12e30 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a  8-byte aligned.*
12e40 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69  * memory, the si
12e50 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20  ze of each page 
12e60 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64  buffer (sz), and
12e70 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
12e80 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ages (N)..** The
12e90 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f   sz argument sho
12ea0 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20  uld be the size 
12eb0 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64  of the largest d
12ec0 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20  atabase page.** 
12ed0 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20  (a power of two 
12ee0 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20  between 512 and 
12ef0 33 32 37 36 38 29 20 70 6c 75 73 20 73 6f 6d 65  32768) plus some
12f00 20 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72   extra bytes for
12f10 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65   each.** page he
12f20 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62  ader.  ^The numb
12f30 65 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65  er of extra byte
12f40 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20  s needed by the 
12f50 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63  page header.** c
12f60 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
12f70 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
12f80 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
12f90 5f 48 44 52 53 5a 5d 20 6f 70 74 69 6f 6e 20 0a  _HDRSZ] option .
12fa0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
12fb0 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 20 5e 49 74  onfig()]..** ^It
12fc0 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
12fd0 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
12fe0 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66  ted memory,.** f
12ff0 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65  or the sz parame
13000 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72  ter to be larger
13010 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e   than necessary.
13020 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61    The first.** a
13030 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
13040 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
13050 79 74 65 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63  yte aligned bloc
13060 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 74 68 61 74  k of memory that
13070 0a 2a 2a 20 69 73 20 61 74 20 6c 65 61 73 74 20  .** is at least 
13080 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
13090 6d 6f 72 79 2c 20 6f 74 68 65 72 77 69 73 65 20  mory, otherwise 
130a0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
130b0 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
130c0 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ned..** ^SQLite 
130d0 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
130e0 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
130f0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
13100 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
13110 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
13120 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
13130 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
13140 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
13150 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
13160 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
13170 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
13180 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
13190 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70  vided by this op
131a0 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  tion, then.** SQ
131b0 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
131c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
131d0 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e  for the addition
131e0 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  al storage space
131f0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
13200 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
13210 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  P]] <dt>SQLITE_C
13220 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
13230 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
13240 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
13250 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
13260 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
13270 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74   buffer .** that
13280 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
13290 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
132a0 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
132b0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a  llocation needs.
132c0 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ** beyond those 
132d0 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20  provided for by 
132e0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
132f0 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b  CRATCH] and.** [
13300 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
13310 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68  GECACHE]..** ^Th
13320 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13330 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f  HEAP option is o
13340 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
13350 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
13360 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68  led.** with eith
13370 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
13380 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53  E_MEMSYS3] or [S
13390 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
133a0 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e  SYS5] and return
133b0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  s.** [SQLITE_ERR
133c0 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f  OR] if invoked o
133d0 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68  therwise..** ^Th
133e0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
133f0 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
13400 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a  E_CONFIG_HEAP:.*
13410 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  * An 8-byte alig
13420 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ned pointer to t
13430 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68  he memory,.** th
13440 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
13450 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
13460 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
13470 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
13480 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  on size..** ^If 
13490 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
134a0 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
134b0 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
134c0 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
134d0 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
134e0 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
134f0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
13500 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
13510 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
13520 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
13530 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
13540 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
13550 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e  NFIG_MALLOC].  ^
13560 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
13570 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
13580 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c  NULL then the al
13590 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
135a0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
135b0 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
135c0 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
135d0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
135e0 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
135f0 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
13600 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
13610 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
13620 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
13630 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
13640 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
13650 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
13660 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
13670 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d  ..** The minimum
13680 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
13690 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a   is capped at 2*
136a0 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20  *12. Reasonable 
136b0 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68  values.** for th
136c0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
136d0 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a  tion size are 2*
136e0 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e  *5 through 2**8.
136f0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13700 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
13710 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
13720 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
13730 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
13740 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
13750 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  EX option takes 
13760 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
13770 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20  t which is a.** 
13780 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
13790 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
137a0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
137b0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
137c0 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
137d0 20 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72   specifies alter
137e0 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
137f0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
13800 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e  to be used.** in
13810 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78   place the mutex
13820 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
13830 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20  into SQLite.)^  
13840 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
13850 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
13860 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
13870 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
13880 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20  hods] structure 
13890 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20  before the call 
138a0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
138b0 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73  onfig()] returns
138c0 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  . ^If SQLite is 
138d0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
138e0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
138f0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
13900 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
13910 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
13920 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
13930 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
13940 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
13950 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
13960 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
13970 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
13980 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
13990 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
139a0 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  IG_MUTEX configu
139b0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
139c0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
139d0 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
139e0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
139f0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
13a00 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13a10 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64  NFIG_GETMUTEX</d
13a20 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
13a30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
13a40 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  ETMUTEX option t
13a50 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
13a60 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
13a70 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
13a80 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
13a90 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
13aa0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
13ab0 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
13ac0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
13ad0 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
13ae0 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
13af0 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
13b00 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
13b10 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
13b20 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
13b30 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
13b40 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
13b50 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
13b60 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
13b70 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
13b80 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
13b90 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
13ba0 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
13bb0 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
13bc0 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53  example.   ^If S
13bd0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
13be0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
13bf0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13c00 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
13c10 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
13c20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
13c30 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
13c40 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
13c50 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
13c60 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
13c70 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
13c80 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
13c90 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
13ca0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
13cb0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
13cc0 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
13cd0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
13ce0 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
13cf0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13d00 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20  FIG_LOOKASIDE]] 
13d10 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13d20 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
13d30 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
13d40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
13d50 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61  KASIDE option ta
13d60 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
13d70 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
13d80 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
13d90 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64  size of lookasid
13da0 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68  e memory on each
13db0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13dc0 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66  ction]..** The f
13dd0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
13de0 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
13df0 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
13e00 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
13e10 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65  he second is the
13e20 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
13e30 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f  ots allocated to
13e40 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
13e50 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28  onnection.)^  ^(
13e60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
13e70 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20  OKASIDE.** sets 
13e80 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f  the <i>default</
13e90 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a  i> lookaside siz
13ea0 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44  e. The [SQLITE_D
13eb0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
13ec0 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20  E].** option to 
13ed0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
13ee0 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65  ig()] can be use
13ef0 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
13f00 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e  lookaside.** con
13f10 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e  figuration on in
13f20 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74  dividual connect
13f30 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ions.)^ </dd>.**
13f40 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13f50 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64  FIG_PCACHE2]] <d
13f60 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13f70 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
13f80 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
13f90 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
13fa0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
13fb0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
13fc0 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70  which is .** a p
13fd0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
13fe0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
13ff0 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
14000 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
14010 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74  ifies.** the int
14020 65 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74  erface to a cust
14030 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
14040 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a  plementation.)^.
14050 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ** ^SQLite makes
14060 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b   a copy of the [
14070 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
14080 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
14090 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
140a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
140b0 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
140c0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
140d0 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
140e0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
140f0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14100 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  2 option takes a
14110 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
14120 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
14130 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
14140 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
14150 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
14160 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
14170 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20  .** the current 
14180 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
14190 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
141a0 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
141b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
141c0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
141d0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
141e0 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
141f0 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d> The SQLITE_CO
14200 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
14210 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
14220 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a  gure the SQLite.
14230 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72  ** global [error
14240 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20   log]..** (^The 
14250 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14260 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
14270 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
14280 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
14290 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
142a0 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
142b0 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
142c0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
142d0 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
142e0 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
142f0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
14300 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
14310 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
14320 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
14330 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
14340 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
14350 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
14360 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
14370 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
14380 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
14390 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
143a0 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
143b0 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
143c0 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
143d0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
143e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
143f0 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
14400 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
14410 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
14420 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
14430 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
14440 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
14450 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
14460 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
14470 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
14480 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
14490 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
144a0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
144b0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
144c0 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
144d0 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
144e0 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
144f0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
14500 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
14510 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
14520 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
14530 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
14540 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
14550 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
14560 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
14570 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
14580 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
14590 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
145a0 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
145b0 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
145c0 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
145d0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
145e0 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
145f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
14600 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
14610 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
14620 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
14630 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
14640 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
14650 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
14660 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
14670 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
14680 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
14690 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
146a0 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
146b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
146c0 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53  I.** <dd>^(The S
146d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
146e0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
146f0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14700 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20  of type int..** 
14710 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  If non-zero, the
14720 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  n URI handling i
14730 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
14740 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
14750 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a  eter is zero,.**
14760 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
14770 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ng is globally d
14780 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55  isabled.)^ ^If U
14790 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
147a0 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c  lobally.** enabl
147b0 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65  ed, all filename
147c0 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
147d0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
147e0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
147f0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
14800 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73  pen16()] or.** s
14810 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
14820 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d   of [ATTACH] com
14830 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70  mands are interp
14840 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72  reted as URIs, r
14850 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20  egardless.** of 
14860 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
14870 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
14880 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74  URI] flag is set
14890 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
148a0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
148b0 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20   is opened. ^If 
148c0 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  it is globally d
148d0 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d  isabled, filenam
148e0 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69  es are.** only i
148f0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
14900 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45  Is if the SQLITE
14910 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69  _OPEN_URI flag i
14920 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a  s set when the.*
14930 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
14940 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
14950 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55   ^(By default, U
14960 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
14970 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62  lobally.** disab
14980 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74  led. The default
14990 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68   value may be ch
149a0 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69  anged by compili
149b0 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ng with the.** [
149c0 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
149d0 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29  symbol defined.)
149e0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
149f0 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
14a00 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64  _INDEX_SCAN]] <d
14a10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14a20 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
14a30 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  CAN.** <dd>^The 
14a40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
14a50 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
14a60 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  N option takes a
14a70 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a   single integer.
14a80 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ** argument whic
14a90 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
14aa0 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e   as a boolean in
14ab0 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65   order to enable
14ac0 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   or disable.** t
14ad0 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
14ae0 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
14af0 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20  ull table scans 
14b00 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74  in the query opt
14b10 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  imizer..** ^The 
14b20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
14b30 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
14b40 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
14b50 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49  ALLOW_COVERING_I
14b60 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69  NDEX_SCAN] compi
14b70 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
14b80 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66  or is "on".** if
14b90 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
14ba0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69  me option is omi
14bb0 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69  tted..** The abi
14bc0 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20  lity to disable 
14bd0 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
14be0 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
14bf0 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
14c00 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73  .** is because s
14c10 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ome incorrectly 
14c20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70  coded legacy app
14c30 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lications might 
14c40 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  malfunction.** w
14c50 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  hen the optimiza
14c60 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
14c70 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20    Providing the 
14c80 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69  ability to.** di
14c90 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69  sable the optimi
14ca0 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68  zation allows th
14cb0 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61  e older, buggy a
14cc0 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
14cd0 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f  to work.** witho
14ce0 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77  ut change even w
14cf0 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f  ith newer versio
14d00 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
14d10 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14d20 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53  FIG_PCACHE]] [[S
14d30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14d40 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  PCACHE]].** <dt>
14d50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14d60 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE and SQLITE_
14d70 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14d80 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
14d90 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
14da0 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
14db0 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
14dc0 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
14dd0 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
14de0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
14df0 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
14e00 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
14e10 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14e20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
14e30 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  OG]].** <dt>SQLI
14e40 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
14e50 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
14e60 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
14e70 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20  lable if sqlite 
14e80 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
14e90 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
14ea0 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70  ENABLE_SQLLOG] p
14eb0 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
14ec0 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20  ro defined. The 
14ed0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73  first argument s
14ee0 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f  hould.** be a po
14ef0 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74  inter to a funct
14f00 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64  ion of type void
14f10 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
14f20 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  3*,const char*, 
14f30 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  int)..** The sec
14f40 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66  ond should be of
14f50 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54   type (void*). T
14f60 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
14f70 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69  nvoked by the li
14f80 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65  brary.** in thre
14f90 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75  e separate circu
14fa0 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69  mstances, identi
14fb0 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75  fied by the valu
14fc0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  e passed as the.
14fd0 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
14fe0 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72  ter. If the four
14ff0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
15000 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  0, then the data
15010 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
15020 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
15030 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
15040 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f   has just been o
15050 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64  pened. The third
15060 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69   argument.** poi
15070 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20  nts to a buffer 
15080 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
15090 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20  ame of the main 
150a0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49  database file. I
150b0 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
150c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20  parameter is 1, 
150d0 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  then the SQL sta
150e0 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20  tement that the 
150f0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a  third parameter.
15100 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73  ** points to has
15110 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75   just been execu
15120 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  ted. Or, if the 
15130 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
15140 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74   is 2, then.** t
15150 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  he connection be
15160 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68  ing passed as th
15170 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
15180 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73  er is being clos
15190 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ed. The.** third
151a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61   parameter is pa
151b0 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69  ssed NULL In thi
151c0 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d  s case.  An exam
151d0 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ple of using thi
151e0 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  s.** configurati
151f0 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  on option can be
15200 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65   seen in the "te
15210 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75  st_sqllog.c" sou
15220 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74  rce file in.** t
15230 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c  he canonical SQL
15240 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ite source tree.
15250 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15260 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
15270 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  _SIZE]].** <dt>S
15280 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
15290 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53  P_SIZE.** <dd>^S
152a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
152b0 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f  P_SIZE takes two
152c0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
152d0 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20  (sqlite3_int64) 
152e0 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61  values.** that a
152f0 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  re the default m
15300 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28  map size limit (
15310 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  the default sett
15320 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47  ing for.** [PRAG
15330 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61  MA mmap_size]) a
15340 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61  nd the maximum a
15350 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
15360 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20   limit..** ^The 
15370 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
15380 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
15390 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61  n by each databa
153a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73  se connection us
153b0 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68  ing.** either th
153c0 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  e [PRAGMA mmap_s
153d0 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72  ize] command, or
153e0 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   by using the.**
153f0 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
15400 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
15410 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d  ontrol.  ^(The m
15420 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
15430 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c  map size.** will
15440 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75   be silently tru
15450 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73  ncated if necess
15460 61 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64  ary so that it d
15470 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74  oes not exceed t
15480 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  he.** compile-ti
15490 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20  me maximum mmap 
154a0 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a  size set by the.
154b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d  ** [SQLITE_MAX_M
154c0 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c  MAP_SIZE] compil
154d0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e  e-time option.)^
154e0 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61  .** ^If either a
154f0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
15500 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69  option is negati
15510 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72  ve, then that ar
15520 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61  gument is.** cha
15530 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70  nged to its comp
15540 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74  ile-time default
15550 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
15560 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
15570 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  APSIZE]].** <dt>
15580 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
15590 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20  N32_HEAPSIZE.** 
155a0 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
155b0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
155c0 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20  PSIZE option is 
155d0 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
155e0 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  f SQLite is.** c
155f0 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64  ompiled for Wind
15600 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51  ows with the [SQ
15610 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f  LITE_WIN32_MALLO
15620 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  C] pre-processor
15630 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65   macro.** define
15640 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  d. ^SQLITE_CONFI
15650 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
15660 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20   takes a 32-bit 
15670 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
15680 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73   value.** that s
15690 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78  pecifies the max
156a0 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65  imum size of the
156b0 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a   created heap..*
156c0 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dl>.**.** [[
156d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
156e0 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20  ACHE_HDRSZ]].** 
156f0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15700 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a  G_PCACHE_HDRSZ.*
15710 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
15720 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
15730 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b  HDRSZ option tak
15740 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61  es a single para
15750 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  meter which.** i
15760 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
15770 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72  n integer and wr
15780 69 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69  ites into that i
15790 6e 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65  nteger the numbe
157a0 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79  r of extra.** by
157b0 74 65 73 20 70 65 72 20 70 61 67 65 20 72 65 71  tes per page req
157c0 75 69 72 65 64 20 66 6f 72 20 65 61 63 68 20 70  uired for each p
157d0 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43  age in [SQLITE_C
157e0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
157f0 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20  ..** The amount 
15800 6f 66 20 65 78 74 72 61 20 73 70 61 63 65 20 72  of extra space r
15810 65 71 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e  equired can chan
15820 67 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ge depending on 
15830 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a  the compiler,.**
15840 20 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d   target platform
15850 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  , and SQLite ver
15860 73 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  sion..** </dl>.*
15870 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15880 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
15890 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
158a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
158b0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
158c0 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
158d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
158e0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
158f0 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
15900 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
15910 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
15920 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
15930 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
15940 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
15950 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15960 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
15970 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
15980 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
15990 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
159a0 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
159b0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
159c0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
159d0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
159e0 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
159f0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
15a00 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
15a10 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15a20 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
15a30 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
15a40 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
15a50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15a60 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
15a70 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
15a80 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
15a90 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
15aa0 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
15ab0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
15ac0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
15ad0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15ae0 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
15af0 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
15b00 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
15b10 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
15b20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
15b30 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
15b40 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
15b50 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
15b60 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
15b70 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
15b80 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
15b90 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
15ba0 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
15bb0 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
15bc0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15bd0 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
15be0 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
15bf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15c00 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
15c10 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
15c20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
15c30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
15c40 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
15c50 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
15c60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15c70 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
15c80 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
15c90 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
15ca0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15cb0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
15cc0 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
15cd0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
15ce0 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
15cf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
15d00 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
15d10 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  20  /* int */.#d
15d20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15d30 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20  FIG_SQLLOG      
15d40 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c   21  /* xSqllog,
15d50 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
15d60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15d70 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20  MMAP_SIZE    22 
15d80 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36   /* sqlite3_int6
15d90 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  4, sqlite3_int64
15da0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15db0 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
15dc0 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33  HEAPSIZE      23
15dd0 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
15de0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15df0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
15e00 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20  DRSZ        24  
15e10 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 0a  /* int *psz */..
15e20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
15e30 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
15e40 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
15e50 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
15e60 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
15e70 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
15e80 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
15e90 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
15ea0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
15eb0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
15ec0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
15ed0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
15ee0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
15ef0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
15f00 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15f10 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
15f20 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
15f30 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
15f40 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
15f50 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
15f60 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
15f70 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
15f80 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
15f90 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
15fa0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
15fb0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
15fc0 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
15fd0 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
15fe0 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
15ff0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
16000 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
16010 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
16020 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
16030 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
16040 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
16050 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
16060 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
16070 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
16080 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
16090 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
160a0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
160b0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
160c0 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
160d0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
160e0 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
160f0 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
16100 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
16110 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
16120 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
16130 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
16140 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
16150 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
16160 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
16170 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
16180 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
16190 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
161a0 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
161b0 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
161c0 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
161d0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
161e0 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
161f0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
16200 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
16210 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
16220 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
16230 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
16240 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
16250 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
16260 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
16270 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
16280 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
16290 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
162a0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
162b0 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
162c0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
162d0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
162e0 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
162f0 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
16300 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
16310 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
16320 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
16330 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
16340 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
16350 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
16360 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
16370 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
16380 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
16390 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
163a0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
163b0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
163c0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
163d0 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
163e0 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
163f0 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
16400 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
16410 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
16420 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  r multiple of 8.
16430 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64    ^(The lookasid
16440 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66  e memory.** conf
16450 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20  iguration for a 
16460 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16470 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ion can only be 
16480 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61  changed when tha
16490 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  t.** connection 
164a0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
164b0 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65   using lookaside
164c0 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f   memory, or in o
164d0 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68  ther words.** wh
164e0 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20  en the "current 
164f0 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20  value" returned 
16500 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64  by.** [sqlite3_d
16510 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c  b_status](D,[SQL
16520 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
16530 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65  SIDE],...) is ze
16540 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ro..** Any attem
16550 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  pt to change the
16560 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
16570 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  y configuration 
16580 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a  when lookaside.*
16590 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75  * memory is in u
165a0 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f  se leaves the co
165b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68  nfiguration unch
165c0 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
165d0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  s .** [SQLITE_BU
165e0 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  SY].)^</dd>.**.*
165f0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
16600 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
16610 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  Y</dt>.** <dd> ^
16620 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
16630 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
16640 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66   disable the enf
16650 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b  orcement of.** [
16660 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
16670 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65  traints].  There
16680 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
16690 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
166a0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
166b0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
166c0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
166d0 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46  s 0 to disable F
166e0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a  K enforcement,.*
166f0 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
16700 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
16710 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ent or negative 
16720 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f  to leave FK enfo
16730 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61  rcement.** uncha
16740 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e  nged.  The secon
16750 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
16760 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
16770 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
16780 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
16790 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
167a0 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e  te whether FK en
167b0 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66  forcement is off
167c0 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77   or on.** follow
167d0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
167e0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
167f0 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
16800 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
16810 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
16820 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
16830 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
16840 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
16850 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
16860 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
16870 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74  ABLE_TRIGGER</dt
16880 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
16890 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
168a0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
168b0 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47  ble [CREATE TRIG
168c0 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e  GER | triggers].
168d0 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
168e0 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
168f0 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
16900 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
16910 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
16920 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
16930 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73  disable triggers
16940 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
16950 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73   enable triggers
16960 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
16970 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
16980 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
16990 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
169a0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
169b0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
169c0 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
169d0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
169e0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
169f0 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65  her triggers are
16a00 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
16a10 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
16a20 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
16a30 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
16a40 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
16a50 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
16a60 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74  which case the t
16a70 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69  rigger setting i
16a80 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
16a90 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
16aa0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
16ab0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
16ac0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20  G_LOOKASIDE     
16ad0 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a    1001  /* void*
16ae0 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
16af0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
16b00 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20  FIG_ENABLE_FKEY 
16b10 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74      1002  /* int
16b20 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
16b30 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
16b40 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20  _ENABLE_TRIGGER 
16b50 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e   1003  /* int in
16b60 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t* */.../*.** CA
16b70 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
16b80 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
16b90 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
16ba0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
16bb0 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
16bc0 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69  lt_codes() routi
16bd0 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
16be0 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65  sables the.** [e
16bf0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
16c00 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
16c10 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78   SQLite. ^The ex
16c20 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
16c30 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
16c40 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
16c50 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
16c60 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a  mpatibility..*/.
16c70 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
16c80 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
16c90 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
16ca0 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
16cb0 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
16cc0 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a  sert Rowid.**.**
16cd0 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
16ce0 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c  most SQLite tabl
16cf0 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b  es (except for [
16d00 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
16d10 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20  ables).** has a 
16d20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
16d30 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
16d40 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b  key called the [
16d50 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d  ROWID | "rowid"]
16d60 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20  . ^The rowid is 
16d70 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
16d80 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
16d90 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
16da0 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
16db0 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
16dc0 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
16dd0 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
16de0 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
16df0 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
16e00 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20  mns. ^If.** the 
16e10 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
16e20 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
16e30 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
16e40 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
16e50 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
16e60 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
16e70 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  wid..**.** ^The 
16e80 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
16e90 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74  ert_rowid(D) int
16ea0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
16eb0 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
16ec0 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  e .** most recen
16ed0 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  t successful [IN
16ee0 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77  SERT] into a row
16ef0 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72  id table or [vir
16f00 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f  tual table].** o
16f10 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
16f20 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73  ction D..** ^Ins
16f30 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f  erts into [WITHO
16f40 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
16f50 20 61 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65   are not recorde
16f60 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63  d..** ^If no suc
16f70 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
16f80 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62  s into rowid tab
16f90 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72  les.** have ever
16fa0 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65   occurred on the
16fb0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16fc0 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e  tion D, .** then
16fd0 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
16fe0 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65  sert_rowid(D) re
16ff0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
17000 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52  * ^(If an [INSER
17010 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  T] occurs within
17020 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 69   a trigger or wi
17030 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20  thin a [virtual 
17040 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64  table].** method
17050 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  , then this rout
17060 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ine will return 
17070 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
17080 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72  he inserted.** r
17090 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ow as long as th
170a0 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
170b0 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
170c0 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  d is running..**
170d0 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72   But once the tr
170e0 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
170f0 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e   table method en
17100 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  ds, the value re
17110 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68  turned .** by th
17120 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72  is routine rever
17130 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61  ts to what it wa
17140 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69  s before the tri
17150 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a  gger or virtual.
17160 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  ** table method 
17170 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  began.)^.**.** ^
17180 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74  An [INSERT] that
17190 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20   fails due to a 
171a0 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
171b0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a  tion is not a.**
171c0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
171d0 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f  ERT] and does no
171e0 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
171f0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
17200 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20  his.** routine. 
17210 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52   ^Thus INSERT OR
17220 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52   FAIL, INSERT OR
17230 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20   IGNORE, INSERT 
17240 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20  OR ROLLBACK,.** 
17250 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42  and INSERT OR AB
17260 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e  ORT make no chan
17270 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72  ges to the retur
17280 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a  n value of this.
17290 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20  ** routine when 
172a0 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20  their insertion 
172b0 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49  fails.  ^(When I
172c0 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
172d0 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  .** encounters a
172e0 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
172f0 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e  ation, it does n
17300 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a  ot fail.  The.**
17310 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65   INSERT continue
17320 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  s to completion 
17330 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72  after deleting r
17340 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a  ows that caused.
17350 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  ** the constrain
17360 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53  t problem so INS
17370 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77  ERT OR REPLACE w
17380 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67  ill always chang
17390 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20  e.** the return 
173a0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e  value of this in
173b0 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a  terface.)^.**.**
173c0 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73   ^For the purpos
173d0 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  es of this routi
173e0 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  ne, an [INSERT] 
173f0 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  is considered to
17400 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75  .** be successfu
17410 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  l even if it is 
17420 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c  subsequently rol
17430 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
17440 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
17450 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53   accessible to S
17460 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69  QL statements vi
17470 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69  a the.** [last_i
17480 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51  nsert_rowid() SQ
17490 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
174a0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
174b0 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73   thread performs
174c0 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20   a new [INSERT] 
174d0 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64  on the same.** d
174e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
174f0 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71  on while the [sq
17500 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
17510 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75  t_rowid()].** fu
17520 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
17530 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67  g and thus chang
17540 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65  es the last inse
17550 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74  rt [rowid],.** t
17560 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
17570 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
17580 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
17590 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e  owid()] is.** un
175a0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
175b0 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20  might not equal 
175c0 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f  either the old o
175d0 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73  r the new.** las
175e0 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
175f0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
17600 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  64 sqlite3_last_
17610 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
17620 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
17630 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
17640 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
17650 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
17660 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
17670 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
17680 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66  er of rows modif
17690 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ied, inserted or
176a0 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74  .** deleted by t
176b0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
176c0 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
176d0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
176e0 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
176f0 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
17700 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63   connection spec
17710 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c  ified by the onl
17720 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  y parameter..** 
17730 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f  ^Executing any o
17740 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c  ther type of SQL
17750 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
17760 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76  not modify the v
17770 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
17780 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f   by this functio
17790 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63  n..**.** ^Only c
177a0 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65  hanges made dire
177b0 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45  ctly by the INSE
177c0 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
177d0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61  LETE statement a
177e0 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
177f0 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61   - auxiliary cha
17800 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
17810 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
17820 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20   triggers], .** 
17830 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
17840 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43  ions] or [REPLAC
17850 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  E] constraint re
17860 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74  solution are not
17870 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a   counted..** .**
17880 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69   Changes to a vi
17890 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
178a0 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b  rcepted by .** [
178b0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
178c0 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20  er | INSTEAD OF 
178d0 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f  triggers] are no
178e0 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20  t counted. ^The 
178f0 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e  value .** return
17900 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68  ed by sqlite3_ch
17910 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74  anges() immediat
17920 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53  ely after an INS
17930 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a  ERT, UPDATE or .
17940 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  ** DELETE statem
17950 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65  ent run on a vie
17960 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  w is always zero
17970 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d  . Only changes m
17980 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20  ade to real .** 
17990 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74  tables are count
179a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73  ed..**.** Things
179b0 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69   are more compli
179c0 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c  cated if the sql
179d0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66  ite3_changes() f
179e0 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78  unction is.** ex
179f0 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74  ecuted while a t
17a00 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69  rigger program i
17a10 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20  s running. This 
17a20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68  may happen if th
17a30 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65  e.** program use
17a40 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  s the [changes()
17a50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20   SQL function], 
17a60 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72  or if some other
17a70 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
17a80 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71  ction invokes sq
17a90 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
17aa0 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74  directly. Essent
17ab0 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75  ially:.** .** <u
17ac0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42  l>.**   <li> ^(B
17ad0 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61  efore entering a
17ae0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
17af0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
17b00 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  ned by.**       
17b10 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
17b20 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73  () function is s
17b30 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20  aved. After the 
17b40 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
17b50 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66  .**        has f
17b60 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69  inished, the ori
17b70 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72  ginal value is r
17b80 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a  estored.)^.** .*
17b90 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69  *   <li> ^(Withi
17ba0 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  n a trigger prog
17bb0 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c  ram each INSERT,
17bc0 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45   UPDATE and DELE
17bd0 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74  TE .**        st
17be0 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65  atement sets the
17bf0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
17c00 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  by sqlite3_chang
17c10 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  es() .**        
17c20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  upon completion 
17c30 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f  as normal. Of co
17c40 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65  urse, this value
17c50 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64   will not includ
17c60 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79  e .**        any
17c70 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d   changes perform
17c80 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65  ed by sub-trigge
17c90 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74  rs, as the sqlit
17ca0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a  e3_changes() .**
17cb0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69          value wi
17cc0 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20  ll be saved and 
17cd0 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65  restored after e
17ce0 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20  ach sub-trigger 
17cf0 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f  has run.)^.** </
17d00 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73  ul>.** .** ^This
17d10 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74   means that if t
17d20 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c  he changes() SQL
17d30 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69   function (or si
17d40 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a  milar) is used.*
17d50 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49  * by the first I
17d60 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
17d70 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
17d80 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
17d90 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72  er, it .** retur
17da0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20  ns the value as 
17db0 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c  set when the cal
17dc0 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62  ling statement b
17dd0 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a  egan executing..
17de0 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65  ** ^If it is use
17df0 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
17e00 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75  or subsequent su
17e10 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ch statement wit
17e20 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a  hin a trigger .*
17e30 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76  * program, the v
17e40 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65  alue returned re
17e50 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65  flects the numbe
17e60 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
17e70 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72  ed by the .** pr
17e80 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55  evious INSERT, U
17e90 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
17ea0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
17eb0 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
17ec0 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
17ed0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
17ee0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
17ef0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
17f00 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
17f10 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
17f20 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
17f30 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
17f40 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
17f50 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
17f60 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
17f70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17f80 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
17f90 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
17fa0 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
17fb0 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
17fc0 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
17fd0 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
17fe0 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
17ff0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
18000 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
18010 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18020 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
18030 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
18040 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
18050 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74  on returns the t
18060 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72  otal number of r
18070 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f  ows inserted, mo
18080 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c  dified or.** del
18090 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53  eted by all [INS
180a0 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f  ERT], [UPDATE] o
180b0 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
180c0 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a  ments completed.
180d0 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74  ** since the dat
180e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
180f0 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63   was opened, inc
18100 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65  luding those exe
18110 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74  cuted as.** part
18120 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67   of trigger prog
18130 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67  rams. ^Executing
18140 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
18150 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
18160 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66  .** does not aff
18170 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65  ect the value re
18180 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
18190 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
181a0 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67  )..** .** ^Chang
181b0 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  es made as part 
181c0 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  of [foreign key 
181d0 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63  actions] are inc
181e0 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  luded in the.** 
181f0 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65  count, but those
18200 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
18210 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
18220 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
18230 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e  re.** not. ^Chan
18240 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
18250 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74  at are intercept
18260 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46  ed by INSTEAD OF
18270 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72   triggers .** ar
18280 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
18290 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  * .** See also t
182a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
182b0 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
182c0 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
182d0 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
182e0 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
182f0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
18300 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
18310 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
18320 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
18330 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
18340 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18350 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
18360 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
18370 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
18380 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
18390 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
183a0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
183b0 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
183c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
183d0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
183e0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
183f0 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
18400 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
18410 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  g Query.**.** ^T
18420 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
18430 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
18440 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
18450 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
18460 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
18470 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
18480 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
18490 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
184a0 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
184b0 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
184c0 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
184d0 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
184e0 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
184f0 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
18500 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
18510 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
18520 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
18530 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
18540 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
18550 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
18560 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
18570 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
18580 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
18590 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
185a0 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
185b0 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
185c0 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
185d0 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
185e0 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
185f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
18600 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
18610 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
18620 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
18630 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
18640 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
18650 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
18660 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
18670 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
18680 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
18690 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
186a0 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
186b0 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
186c0 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
186d0 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
186e0 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
186f0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
18700 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
18710 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
18720 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
18730 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
18740 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
18750 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
18760 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
18770 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
18780 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
18790 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
187a0 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
187b0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
187c0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
187d0 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
187e0 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
187f0 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
18800 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
18810 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18820 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
18830 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
18840 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
18850 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
18860 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
18870 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
18880 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
18890 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
188a0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
188b0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
188c0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
188d0 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
188e0 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
188f0 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
18900 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
18910 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
18920 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
18930 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
18940 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
18950 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
18960 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
18970 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
18980 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
18990 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
189a0 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
189b0 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
189c0 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
189d0 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
189e0 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
189f0 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
18a00 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
18a10 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
18a20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
18a30 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
18a40 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
18a50 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
18a60 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
18a70 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
18a80 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
18a90 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
18aa0 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
18ab0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
18ac0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
18ad0 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
18ae0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
18af0 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
18b00 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
18b10 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
18b20 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76  ely happen..*/.v
18b30 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
18b40 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
18b50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18b60 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
18b70 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
18b80 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
18b90 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
18ba0 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
18bb0 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
18bc0 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
18bd0 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
18be0 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
18bf0 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
18c00 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
18c10 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
18c20 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
18c30 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
18c40 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
18c50 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
18c60 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
18c70 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
18c80 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
18c90 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
18ca0 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
18cb0 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
18cc0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
18cd0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
18ce0 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
18cf0 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
18d00 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
18d10 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
18d20 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
18d30 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
18d40 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
18d50 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
18d60 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
18d70 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
18d80 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
18d90 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
18da0 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
18db0 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
18dc0 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
18dd0 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
18de0 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
18df0 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
18e00 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
18e10 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
18e20 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
18e30 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
18e40 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
18e50 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
18e60 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
18e70 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
18e80 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
18e90 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
18ea0 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
18eb0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
18ec0 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
18ed0 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
18ee0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
18ef0 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
18f00 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
18f10 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
18f20 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
18f30 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
18f40 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
18f50 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
18f60 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
18f70 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
18f80 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
18f90 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
18fa0 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
18fb0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
18fc0 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
18fd0 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
18fe0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
18ff0 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
19000 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
19010 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
19020 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
19030 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
19040 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
19050 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
19060 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
19070 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
19080 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
19090 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
190a0 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
190b0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
190c0 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
190d0 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
190e0 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
190f0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
19100 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
19110 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
19120 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
19130 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
19140 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
19150 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
19160 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
19170 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
19180 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
19190 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
191a0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
191b0 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
191c0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
191d0 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
191e0 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
191f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
19200 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
19210 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
19220 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
19230 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73  * KEYWORDS: {bus
19240 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
19250 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65  ck} {busy handle
19260 72 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r}.**.** ^The sq
19270 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
19280 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e  er(D,X,P) routin
19290 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
192a0 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20  k function X.** 
192b0 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
192c0 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d  voked with argum
192d0 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a  ent P whenever.*
192e0 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
192f0 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 61  made to access a
19300 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
19310 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
19320 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
19330 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20  nection] D when 
19340 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
19350 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
19360 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65   the table locke
19370 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  d..** The sqlite
19380 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
19390 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
193a0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a  ed to implement.
193b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
193c0 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20  _timeout()] and 
193d0 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
193e0 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  eout]..**.** ^If
193f0 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
19400 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
19410 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
19420 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
19430 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
19440 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
19450 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
19460 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
19470 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
19480 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
19490 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
194a0 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
194b0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
194c0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
194d0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
194e0 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
194f0 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
19500 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
19510 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
19520 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
19530 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
19540 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
19550 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
19560 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
19570 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
19580 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
19590 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
195a0 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
195b0 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72  d previously for
195c0 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e   the same lockin
195d0 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
195e0 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
195f0 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
19600 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
19610 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
19620 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
19630 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
19640 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69   [SQLITE_BUSY] i
19650 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f  s returned.** to
19660 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
19670 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
19680 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
19690 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
196a0 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
196b0 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
196c0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
196d0 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70  nd the cycle rep
196e0 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eats..**.** The 
196f0 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75  presence of a bu
19700 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20  sy handler does 
19710 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68  not guarantee th
19720 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  at it will be in
19730 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68  voked.** when th
19740 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74  ere is lock cont
19750 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69  ention. ^If SQLi
19760 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
19770 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
19780 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
19790 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
197a0 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
197b0 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
197c0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
197d0 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  BUSY].** to the 
197e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74  application inst
197f0 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
19800 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e  the .** busy han
19810 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
19820 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
19830 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
19840 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
19850 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
19860 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
19870 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
19880 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
19890 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
198a0 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
198b0 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
198c0 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
198d0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
198e0 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
198f0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
19900 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
19910 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
19920 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
19930 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
19940 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
19950 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
19960 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
19970 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
19980 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
19990 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
199a0 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
199b0 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
199c0 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
199d0 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
199e0 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
199f0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
19a00 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
19a10 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
19a20 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
19a30 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
19a40 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
19a50 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
19a60 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
19a70 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
19a80 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
19a90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
19aa0 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
19ab0 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
19ac0 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
19ad0 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
19ae0 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
19af0 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ned for each.** 
19b00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
19b10 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20  tion].  Setting 
19b20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
19b30 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a  er clears any.**
19b40 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
19b50 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74  handler.)^  ^Not
19b60 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
19b70 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
19b80 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76  eout()].** or ev
19b90 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41  aluating [PRAGMA
19ba0 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d   busy_timeout=N]
19bb0 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65   will change the
19bc0 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72  .** busy handler
19bd0 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20   and thus clear 
19be0 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73  any previously s
19bf0 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  et busy handler.
19c00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20  .**.** The busy 
19c10 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20  callback should 
19c20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74  not take any act
19c30 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66  ions which modif
19c40 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  y the.** databas
19c50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
19c60 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
19c70 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20  sy handler.  In 
19c80 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20  other words,.** 
19c90 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19ca0 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
19cb0 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  t.  Any such act
19cc0 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
19cd0 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
19ce0 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
19cf0 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
19d00 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
19d10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19d20 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
19d30 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
19d40 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
19d50 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
19d60 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
19d70 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
19d80 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
19d90 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
19da0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
19db0 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
19dc0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
19dd0 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
19de0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
19df0 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
19e00 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
19e10 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
19e20 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
19e30 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
19e40 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
19e50 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
19e60 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
19e70 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
19e80 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
19e90 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
19ea0 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
19eb0 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
19ec0 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
19ed0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
19ee0 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
19ef0 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
19f00 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
19f10 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
19f20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
19f30 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  E_BUSY]..**.** ^
19f40 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
19f50 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
19f60 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
19f70 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
19f80 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
19f90 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
19fa0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
19fb0 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
19fc0 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
19fd0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
19fe0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
19ff0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e  onnection] at an
1a000 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
1a010 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
1a020 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
1a030 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
1a040 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1a050 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
1a060 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
1a070 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
1a080 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
1a090 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29  ler is cleared.)
1a0a0 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
1a0b0 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  :  [PRAGMA busy_
1a0c0 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20  timeout].*/.int 
1a0d0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1a0e0 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  eout(sqlite3*, i
1a0f0 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  nt ms);../*.** C
1a100 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69  API3REF: Conveni
1a110 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f  ence Routines Fo
1a120 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65  r Running Querie
1a130 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  s.**.** This is 
1a140 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  a legacy interfa
1a150 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65  ce that is prese
1a160 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rved for backwar
1a170 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
1a180 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73  ..** Use of this
1a190 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
1a1a0 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  t recommended..*
1a1b0 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a  *.** Definition:
1a1c0 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62   A <b>result tab
1a1d0 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79  le</b> is memory
1a1e0 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20   data structure 
1a1f0 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a  created by the.*
1a200 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  * [sqlite3_get_t
1a210 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63  able()] interfac
1a220 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62  e.  A result tab
1a230 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a  le records the.*
1a240 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79  * complete query
1a250 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e   results from on
1a260 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65  e or more querie
1a270 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  s..**.** The tab
1a280 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20  le conceptually 
1a290 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  has a number of 
1a2a0 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73  rows and columns
1a2b0 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20  .  But.** these 
1a2c0 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20  numbers are not 
1a2d0 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75  part of the resu
1a2e0 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e  lt table itself.
1a2f0 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65    These.** numbe
1a300 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20  rs are obtained 
1a310 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74  separately.  Let
1a320 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   N be the number
1a330 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20   of rows.** and 
1a340 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  M be the number 
1a350 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a  of columns..**.*
1a360 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1a370 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
1a380 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f  pointers to zero
1a390 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1a3a0 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  8 strings..** Th
1a3b0 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20  ere are (N+1)*M 
1a3c0 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  elements in the 
1a3d0 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73  array.  The firs
1a3e0 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69  t M pointers poi
1a3f0 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65  nt.** to zero-te
1a400 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
1a410 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74   that  contain t
1a420 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20  he names of the 
1a430 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20  columns..** The 
1a440 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65  remaining entrie
1a450 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71  s all point to q
1a460 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e  uery results.  N
1a470 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c  ULL values resul
1a480 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69  t.** in NULL poi
1a490 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65  nters.  All othe
1a4a0 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20  r values are in 
1a4b0 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f  their UTF-8 zero
1a4c0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
1a4d0 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61  tring representa
1a4e0 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64  tion as returned
1a4f0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
1a500 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
1a510 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1a520 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20  e might consist 
1a530 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d  of one or more m
1a540 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1a550 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  s..** It is not 
1a560 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72  safe to pass a r
1a570 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65  esult table dire
1a580 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33  ctly to [sqlite3
1a590 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72  _free()]..** A r
1a5a0 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75  esult table shou
1a5b0 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ld be deallocate
1a5c0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1a5d0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a  _free_table()]..
1a5e0 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78  **.** ^(As an ex
1a5f0 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73  ample of the res
1a600 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74  ult table format
1a610 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72  , suppose a quer
1a620 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61  y result.** is a
1a630 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1a640 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1a650 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d  e>.**        Nam
1a660 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a  e        | Age.*
1a670 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d  *        -------
1a680 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1a690 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65  .**        Alice
1a6a0 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20         | 43.**  
1a6b0 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20        Bob       
1a6c0 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20    | 28.**       
1a6d0 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32   Cindy       | 2
1a6e0 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  1.** </pre></blo
1a6f0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1a700 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c  here are two col
1a710 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74  umn (M==2) and t
1a720 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29  hree rows (N==3)
1a730 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72  .  Thus the.** r
1a740 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20  esult table has 
1a750 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70  8 entries.  Supp
1a760 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74  ose the result t
1a770 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a  able is stored.*
1a780 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61  * in an array na
1a790 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54  mes azResult.  T
1a7a0 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c  hen azResult hol
1a7b0 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a  ds this content:
1a7c0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1a7d0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1a7e0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1a7f0 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20  0] = "Name";.** 
1a800 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1a810 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a  #91;1] = "Age";.
1a820 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1a830 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69  lt&#91;2] = "Ali
1a840 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ce";.**        a
1a850 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d  zResult&#91;3] =
1a860 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "43";.**       
1a870 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d   azResult&#91;4]
1a880 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20   = "Bob";.**    
1a890 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1a8a0 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20  ;5] = "28";.**  
1a8b0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1a8c0 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b  91;6] = "Cindy";
1a8d0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1a8e0 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31  ult&#91;7] = "21
1a8f0 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
1a900 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
1a910 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
1a920 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74  et_table() funct
1a930 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e  ion evaluates on
1a940 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d  e or more.** sem
1a950 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64  icolon-separated
1a960 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1a970 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  in the zero-term
1a980 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20  inated UTF-8.** 
1a990 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e  string of its 2n
1a9a0 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
1a9b0 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
1a9c0 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a   table to the.**
1a9d0 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69   pointer given i
1a9e0 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  n its 3rd parame
1a9f0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ter..**.** After
1aa00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1aa10 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
1aa20 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  th the result fr
1aa30 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  om sqlite3_get_t
1aa40 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75  able(),.** it mu
1aa50 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75  st pass the resu
1aa60 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72  lt table pointer
1aa70 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
1aa80 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65  _table() in orde
1aa90 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20  r to.** release 
1aaa0 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  the memory that 
1aab0 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42  was malloced.  B
1aac0 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61  ecause of the wa
1aad0 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
1aae0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70  3_malloc()] happ
1aaf0 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74  ens within sqlit
1ab00 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20  e3_get_table(), 
1ab10 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66  the calling.** f
1ab20 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  unction must not
1ab30 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71   try to call [sq
1ab40 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69  lite3_free()] di
1ab50 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a  rectly.  Only.**
1ab60 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1ab70 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20  able()] is able 
1ab80 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  to release the m
1ab90 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61  emory properly a
1aba0 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a  nd safely..**.**
1abb0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
1abc0 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61  _table() interfa
1abd0 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ce is implemente
1abe0 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61  d as a wrapper a
1abf0 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
1ac00 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20  3_exec()].  The 
1ac10 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1ac20 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  e() routine does
1ac30 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73   not have access
1ac40 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72  .** to any inter
1ac50 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75  nal data structu
1ac60 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  res of SQLite.  
1ac70 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65  It uses only the
1ac80 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72   public.** inter
1ac90 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72  face defined her
1aca0 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75  e.  As a consequ
1acb0 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61  ence, errors tha
1acc0 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a  t occur in the.*
1acd0 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20  * wrapper layer 
1ace0 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69  outside of the i
1acf0 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33  nternal [sqlite3
1ad00 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72  _exec()] call ar
1ad10 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74  e not.** reflect
1ad20 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74  ed in subsequent
1ad30 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1ad40 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72  e3_errcode()] or
1ad50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
1ad60 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  msg()]..*/.int s
1ad70 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1ad80 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1ad90 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
1ada0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
1adb0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1adc0 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20  Sql,     /* SQL 
1add0 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
1ade0 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a  */.  char ***paz
1adf0 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65  Result,    /* Re
1ae00 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
1ae10 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52  ry */.  int *pnR
1ae20 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ow,           /*
1ae30 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1ae40 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
1ae50 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ere */.  int *pn
1ae60 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f  Column,        /
1ae70 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1ae80 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
1ae90 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
1aea0 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20  r **pzErrmsg    
1aeb0 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
1aec0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1aed0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1aee0 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20  free_table(char 
1aef0 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a  **result);../*.*
1af00 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d  * CAPI3REF: Form
1af10 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69  atted String Pri
1af20 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  nting Functions.
1af30 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1af40 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c  ines are work-al
1af50 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69  ikes of the "pri
1af60 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66  ntf()" family of
1af70 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72   functions.** fr
1af80 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
1af90 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  C library..**.**
1afa0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70   ^The sqlite3_mp
1afb0 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69  rintf() and sqli
1afc0 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72  te3_vmprintf() r
1afd0 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68  outines write th
1afe0 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  eir.** results i
1aff0 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
1b000 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
1b010 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20  3_malloc()]..** 
1b020 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
1b030 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77  rned by these tw
1b040 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  o routines shoul
1b050 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64  d be.** released
1b060 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   by [sqlite3_fre
1b070 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75  e()].  ^Both rou
1b080 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a  tines return a.*
1b090 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
1b0a0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1b0b0 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74  c()] is unable t
1b0c0 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67  o allocate enoug
1b0d0 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68  h.** memory to h
1b0e0 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e  old the resultin
1b0f0 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  g string..**.** 
1b100 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e  ^(The sqlite3_sn
1b110 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1b120 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22   is similar to "
1b130 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d  snprintf()" from
1b140 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
1b150 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65   C library.  The
1b160 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74   result is writt
1b170 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62  en into the.** b
1b180 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61  uffer supplied a
1b190 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1b1a0 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a  ameter whose siz
1b1b0 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a  e is given by.**
1b1c0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
1b1d0 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20  eter. Note that 
1b1e0 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
1b1f0 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61  .** first two pa
1b200 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65  rameters is reve
1b210 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e  rsed from snprin
1b220 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73  tf().)^  This is
1b230 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61   an.** historica
1b240 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20  l accident that 
1b250 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20  cannot be fixed 
1b260 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
1b270 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
1b280 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28  mpatibility.  ^(
1b290 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73  Note also that s
1b2a0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1b2b0 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70  ).** returns a p
1b2c0 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75  ointer to its bu
1b2d0 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  ffer instead of 
1b2e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
1b2f0 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75   characters actu
1b300 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74  ally written int
1b310 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20  o the buffer.)^ 
1b320 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a   We admit that.*
1b330 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
1b340 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74  characters writt
1b350 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f  en would be a mo
1b360 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e  re useful return
1b370 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65  .** value but we
1b380 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74   cannot change t
1b390 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
1b3a0 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
1b3b0 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77  rintf().** now w
1b3c0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
1b3d0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1b3e0 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73  *.** ^As long as
1b3f0 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65   the buffer size
1b400 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
1b410 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73   zero, sqlite3_s
1b420 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61  nprintf().** gua
1b430 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
1b440 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79   buffer is alway
1b450 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
1b460 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a  d.  ^The first.*
1b470 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
1b480 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
1b490 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
1b4a0 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
1b4b0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
1b4c0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
1b4d0 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
1b4e0 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
1b4f0 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
1b500 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
1b510 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
1b520 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1b530 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  _vsnprintf() rou
1b540 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67  tine is a vararg
1b550 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c  s version of sql
1b560 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e  ite3_snprintf().
1b570 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1b580 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d  tines all implem
1b590 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  ent some additio
1b5a0 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a  nal formatting.*
1b5b0 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61  * options that a
1b5c0 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
1b5d0 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73  nstructing SQL s
1b5e0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c  tatements..** Al
1b5f0 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70  l of the usual p
1b600 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69  rintf() formatti
1b610 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79  ng options apply
1b620 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20  .  In addition, 
1b630 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20  there.** is are 
1b640 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20  "%q", "%Q", and 
1b650 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%z" options..**
1b660 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74  .** ^(The %q opt
1b670 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1b680 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62  s in that it sub
1b690 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74  stitutes a nul-t
1b6a0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1b6b0 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67  ing from the arg
1b6c0 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74  ument list.  But
1b6d0 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73   %q also doubles
1b6e0 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72   every '\'' char
1b6f0 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20  acter..** %q is 
1b700 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65  designed for use
1b710 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67   inside a string
1b720 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20   literal.)^  By 
1b730 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
1b740 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
1b750 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
1b760 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
1b770 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
1b780 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
1b790 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
1b7a0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73   For example, as
1b7b0 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20  sume the string 
1b7c0 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63  variable zText c
1b7d0 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
1b7e0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1b7f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1b800 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
1b810 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
1b820 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
1b830 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1b840 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
1b850 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
1b860 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
1b870 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1b880 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1b890 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
1b8a0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
1b8b0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
1b8c0 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
1b8d0 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
1b8e0 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
1b8f0 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
1b900 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
1b910 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
1b920 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1b930 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
1b940 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
1b950 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
1b960 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
1b970 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
1b980 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
1b990 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
1b9a0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1b9b0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1b9c0 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
1b9d0 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
1b9e0 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
1b9f0 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
1ba00 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1ba10 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
1ba20 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
1ba30 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
1ba40 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
1ba50 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
1ba60 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
1ba70 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
1ba80 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1ba90 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1baa0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1bab0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1bac0 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
1bad0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1bae0 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
1baf0 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
1bb00 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
1bb10 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
1bb20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c  you should.** al
1bb30 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
1bb40 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
1bb50 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
1bb60 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
1bb70 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ral..**.** ^(The
1bb80 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %Q option works
1bb90 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20   like %q except 
1bba0 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e  it also adds sin
1bbb0 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e  gle quotes aroun
1bbc0 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65  d.** the outside
1bbd0 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74   of the total st
1bbe0 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61  ring.  Additiona
1bbf0 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61  lly, if the para
1bc00 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20  meter in the.** 
1bc10 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73  argument list is
1bc20 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
1bc30 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20   %Q substitutes 
1bc40 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20  the text "NULL" 
1bc50 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67  (without.** sing
1bc60 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53  le quotes).)^  S
1bc70 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  o, for example, 
1bc80 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a  one could say:.*
1bc90 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1bca0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1bcb0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1bcc0 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1bcd0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1bce0 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a  S(%Q)", zText);.
1bcf0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
1bd00 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
1bd10 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
1bd20 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
1bd30 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1bd40 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  te>.**.** The co
1bd50 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65  de above will re
1bd60 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53  nder a correct S
1bd70 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
1bd80 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69  the zSQL.** vari
1bd90 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65  able even if the
1bda0 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20   zText variable 
1bdb0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1bdc0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22  r..**.** ^(The "
1bdd0 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
1bde0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1bdf0 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74   "%s" but with t
1be00 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74  he.** addition t
1be10 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74  hat after the st
1be20 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65  ring has been re
1be30 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e  ad and copied in
1be40 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  to.** the result
1be50 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
1be60 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  )] is called on 
1be70 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1be80 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c  .)^.*/.char *sql
1be90 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e  ite3_mprintf(con
1bea0 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63  st char*,...);.c
1beb0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70  har *sqlite3_vmp
1bec0 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
1bed0 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61  *, va_list);.cha
1bee0 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  r *sqlite3_snpri
1bef0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
1bf00 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
1bf10 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
1bf20 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
1bf30 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
1bf40 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a  va_list);../*.**
1bf50 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
1bf60 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62  y Allocation Sub
1bf70 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65  system.**.** The
1bf80 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
1bf90 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f  s these three ro
1bfa0 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f  utines for all o
1bfb0 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74  f its own.** int
1bfc0 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ernal memory all
1bfd0 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22  ocation needs. "
1bfe0 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65  Core" in the pre
1bff0 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a  vious sentence.*
1c000 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  * does not inclu
1c010 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  de operating-sys
1c020 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53  tem specific VFS
1c030 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
1c040 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73    The.** Windows
1c050 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65   VFS uses native
1c060 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
1c070 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70  ee() for some op
1c080 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
1c090 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ^The sqlite3_mal
1c0a0 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65  loc() routine re
1c0b0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1c0c0 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66  to a block.** of
1c0d0 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74   memory at least
1c0e0 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67   N bytes in leng
1c0f0 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  th, where N is t
1c100 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
1c110 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
1c120 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20  loc() is unable 
1c130 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63  to obtain suffic
1c140 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d  ient free.** mem
1c150 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ory, it returns 
1c160 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1c170 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74   ^If the paramet
1c180 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  er N to.** sqlit
1c190 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a  e3_malloc() is z
1c1a0 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ero or negative 
1c1b0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c  then sqlite3_mal
1c1c0 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  loc() returns.**
1c1d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1c1e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1c1f0 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20  te3_malloc64(N) 
1c200 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75  routine works ju
1c210 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74  st like.** sqlit
1c220 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63  e3_malloc(N) exc
1c230 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e  ept that N is an
1c240 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74   unsigned 64-bit
1c250 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64   integer instead
1c260 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20  .** of a signed 
1c270 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a  32-bit integer..
1c280 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
1c290 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
1c2a0 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
1c2b0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
1c2c0 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
1c2d0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1c2e0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
1c2f0 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
1c300 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
1c310 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
1c320 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66    ^The sqlite3_f
1c330 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
1c340 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
1c350 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1c360 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
1c370 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
1c380 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
1c390 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
1c3a0 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
1c3b0 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
1c3c0 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
1c3d0 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
1c3e0 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
1c3f0 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
1c400 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
1c410 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
1c420 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
1c430 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
1c440 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
1c450 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
1c460 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
1c470 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
1c480 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1c490 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
1c4a0 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
1c4b0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
1c4c0 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
1c4d0 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
1c4e0 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
1c4f0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1c500 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1c510 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
1c520 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  ^The sqlite3_rea
1c530 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66  lloc(X,N) interf
1c540 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
1c550 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
1c560 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
1c570 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c  ion X to be at l
1c580 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a  east N bytes..**
1c590 20 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d   ^If the X param
1c5a0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1c5b0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20  realloc(X,N).** 
1c5c0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1c5d0 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
1c5e0 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
1c5f0 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
1c600 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1c610 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70  ..** ^If the N p
1c620 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1c630 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1c640 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
1c650 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
1c660 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
1c670 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
1c680 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1c690 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20  te3_free(X)..** 
1c6a0 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  ^sqlite3_realloc
1c6b0 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20  (X,N) returns a 
1c6c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
1c6d0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
1c6e0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  * of at least N 
1c6f0 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72  bytes in size or
1c700 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69   NULL if insuffi
1c710 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20  cient memory is 
1c720 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49  available..** ^I
1c730 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20  f M is the size 
1c740 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
1c750 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69  ocation, then mi
1c760 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20  n(N,M) bytes.** 
1c770 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
1c780 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69  ocation are copi
1c790 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69  ed into the begi
1c7a0 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20  nning of buffer 
1c7b0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
1c7c0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1c7d0 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  ,N) and the prio
1c7e0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1c7f0 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71  freed..** ^If sq
1c800 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1c810 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  N) returns NULL 
1c820 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76  and N is positiv
1c830 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70  e, then the.** p
1c840 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1c850 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a  is not freed..**
1c860 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1c870 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20  _realloc64(X,N) 
1c880 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73  interfaces works
1c890 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20   the same as.** 
1c8a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c8b0 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74  X,N) except that
1c8c0 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75   N is a 64-bit u
1c8d0 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
1c8e0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
1c8f0 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
1c900 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  teger..**.** ^If
1c910 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61   X is a memory a
1c920 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f  llocation previo
1c930 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
1c940 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1c950 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  c(),.** sqlite3_
1c960 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69  malloc64(), sqli
1c970 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f  te3_realloc(), o
1c980 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1c990 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73  c64(), then.** s
1c9a0 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1c9b0 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65  returns the size
1c9c0 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20   of that memory 
1c9d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79  allocation in by
1c9e0 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  tes..** ^The val
1c9f0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
1ca00 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1ca10 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20  might be larger 
1ca20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a  than the number.
1ca30 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75  ** of bytes requ
1ca40 65 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73  ested when X was
1ca50 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66   allocated.  ^If
1ca60 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   X is a NULL poi
1ca70 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  nter then.** sql
1ca80 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65  ite3_msize(X) re
1ca90 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20  turns zero.  If 
1caa0 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65  X points to some
1cab0 74 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f  thing that is no
1cac0 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69  t.** the beginni
1cad0 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  ng of memory all
1cae0 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69  ocation, or if i
1caf0 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f  t points to a fo
1cb00 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20  rmerly.** valid 
1cb10 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1cb20 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62  n that has now b
1cb30 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20  een freed, then 
1cb40 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
1cb50 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  of sqlite3_msize
1cb60 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  (X) is undefined
1cb70 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61   and possibly ha
1cb80 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rmful..**.** ^Th
1cb90 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
1cba0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
1cbb0 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  loc(), sqlite3_r
1cbc0 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c  ealloc(),.** sql
1cbd0 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c  ite3_malloc64(),
1cbe0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
1cbf0 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61  lloc64().** is a
1cc00 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
1cc10 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
1cc20 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72  yte boundary, or
1cc30 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20   to a.** 4 byte 
1cc40 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20  boundary if the 
1cc50 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41  [SQLITE_4_BYTE_A
1cc60 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63  LIGNED_MALLOC] c
1cc70 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
1cc80 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
1cc90 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
1cca0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
1ccb0 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
1ccc0 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
1ccd0 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
1cce0 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
1ccf0 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
1cd00 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
1cd10 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
1cd20 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
1cd30 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
1cd40 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
1cd50 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
1cd60 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
1cd70 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
1cd80 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1cd90 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
1cda0 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f  ..**.** Prior to
1cdb0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1cdc0 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64  3.7.10, the Wind
1cdd0 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
1cde0 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a   layer called.**
1cdf0 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
1ce00 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1ce10 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
1ce20 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
1ce30 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
1ce40 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
1ce50 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
1ce60 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
1ce70 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
1ce80 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
1ce90 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
1cea0 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
1ceb0 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
1cec0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77  ocation errors w
1ced0 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75  ere detected, bu
1cee0 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72  t.** they were r
1cef0 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
1cf00 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
1cf10 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
1cf20 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
1cf30 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
1cf40 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
1cf50 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
1cf60 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1cf70 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1cf80 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
1cf90 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
1cfa0 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
1cfb0 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
1cfc0 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
1cfd0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
1cfe0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
1cff0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1d000 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
1d010 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
1d020 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
1d030 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
1d040 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
1d050 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
1d060 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
1d070 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
1d080 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
1d090 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
1d0a0 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
1d0b0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1d0c0 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  ]..*/.void *sqli
1d0d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
1d0e0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d  .void *sqlite3_m
1d0f0 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f  alloc64(sqlite3_
1d100 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73  uint64);.void *s
1d110 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76  qlite3_realloc(v
1d120 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
1d130 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
1d140 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74  c64(void*, sqlit
1d150 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64  e3_uint64);.void
1d160 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
1d170 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69  id*);.sqlite3_ui
1d180 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69  nt64 sqlite3_msi
1d190 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ze(void*);../*.*
1d1a0 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1d1b0 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
1d1c0 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51  tistics.**.** SQ
1d1d0 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
1d1e0 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
1d1f0 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
1d200 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
1d210 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
1d220 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
1d230 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
1d240 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1d250 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
1d260 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
1d270 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
1d280 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
1d290 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  bsystem..**.** ^
1d2a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
1d2b0 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
1d2c0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
1d2d0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
1d2e0 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  ** of memory cur
1d2f0 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
1d300 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
1d310 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20   not freed)..** 
1d320 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1d330 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1d340 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
1d350 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
1d360 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
1d370 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1d380 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68  ] since the high
1d390 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77  -water mark.** w
1d3a0 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20  as last reset.  
1d3b0 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
1d3c0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1d3d0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1d3e0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1d3f0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1d400 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
1d410 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65  overhead.** adde
1d420 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
1d430 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
1d440 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
1d450 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20  lloc()],.** but 
1d460 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
1d470 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
1d480 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
1d490 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69  library.** routi
1d4a0 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
1d4b0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
1d4c0 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  call..**.** ^The
1d4d0 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
1d4e0 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
1d4f0 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
1d500 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c  value of.** [sql
1d510 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1d520 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ()] if and only 
1d530 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1d540 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
1d550 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1d560 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54  ()] is true.  ^T
1d570 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1d580 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
1d590 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1d5a0 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
1d5b0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1d5c0 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
1d5d0 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  et..*/.sqlite3_i
1d5e0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1d5f0 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
1d600 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
1d610 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1d620 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
1d630 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
1d640 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
1d650 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
1d660 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c  erator.**.** SQL
1d670 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68  ite contains a h
1d680 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
1d690 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72  do-random number
1d6a0 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47   generator (PRNG
1d6b0 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c  ) used to.** sel
1d6c0 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49  ect random [ROWI
1d6d0 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e  D | ROWIDs] when
1d6e0 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72   inserting new r
1d6f0 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61  ecords into a ta
1d700 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65  ble that.** alre
1d710 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72  ady uses the lar
1d720 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52  gest possible [R
1d730 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47  OWID].  The PRNG
1d740 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f   is also used fo
1d750 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69  r.** the build-i
1d760 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72  n random() and r
1d770 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20  andomblob() SQL 
1d780 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73  functions.  This
1d790 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
1d7a0 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  s.** application
1d7b0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
1d7c0 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74  same PRNG for ot
1d7d0 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  her purposes..**
1d7e0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74  .** ^A call to t
1d7f0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
1d800 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
1d810 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
1d820 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20  ffer P..** ^The 
1d830 50 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20  P parameter can 
1d840 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
1d850 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69  r..**.** ^If thi
1d860 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f  s routine has no
1d870 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c  t been previousl
1d880 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74  y called or if t
1d890 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63  he previous.** c
1d8a0 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74  all had N less t
1d8b0 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c  han one or a NUL
1d8c0 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c  L pointer for P,
1d8d0 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69   then the PRNG i
1d8e0 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e  s.** seeded usin
1d8f0 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  g randomness obt
1d900 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78  ained from the x
1d910 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f  Randomness metho
1d920 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61  d of.** the defa
1d930 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
1d940 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66  ] object..** ^If
1d950 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
1d960 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
1d970 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31  ne had an N of 1
1d980 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a   or more and a.*
1d990 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65  * non-NULL P the
1d9a0 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e  n the pseudo-ran
1d9b0 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72  domness is gener
1d9c0 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c  ated.** internal
1d9d0 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72  ly and without r
1d9e0 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b  ecourse to the [
1d9f0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61  sqlite3_vfs] xRa
1da00 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68  ndomness.** meth
1da10 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  od..*/.void sqli
1da20 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
1da30 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
1da40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1da50 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
1da60 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
1da70 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  backs.**.** ^Thi
1da80 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
1da90 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ers an authorize
1daa0 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
1dab0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
1dac0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1dad0 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20  tion], supplied 
1dae0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
1daf0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61  ument..** ^The a
1db00 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1db10 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
1db20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1db30 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
1db40 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
1db50 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
1db60 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
1db70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1db80 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1db90 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e  _prepare16()] an
1dba0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
1dbb0 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74  re16_v2()].  ^At
1dbc0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e   various.** poin
1dbd0 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f  ts during the co
1dbe0 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73  mpilation proces
1dbf0 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62  s, as logic is b
1dc00 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20  eing created.** 
1dc10 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
1dc20 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  us actions, the 
1dc30 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1dc40 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  ack is invoked t
1dc50 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73  o.** see if thos
1dc60 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  e actions are al
1dc70 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74  lowed.  ^The aut
1dc80 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1dc90 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
1dca0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
1dcb0 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
1dcc0 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
1dcd0 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
1dce0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
1dcf0 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
1dd00 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1dd10 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
1dd20 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
1dd30 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
1dd40 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
1dd50 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
1dd60 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
1dd70 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
1dd80 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75  ror.  ^If the au
1dd90 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1dda0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
1ddb0 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
1ddc0 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
1ddd0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
1dde0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
1ddf0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
1de00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1de10 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
1de20 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
1de30 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
1de40 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
1de50 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
1de60 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
1de70 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1de80 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1de90 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
1dea0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
1deb0 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
1dec0 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61  k.  ^When the ca
1ded0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1dee0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
1def0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
1df00 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
1df10 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
1df20 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
1df30 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
1df40 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
1df50 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
1df60 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
1df70 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
1df80 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ied. .**.** ^The
1df90 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1dfa0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1dfb0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
1dfc0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
1dfd0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
1dfe0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
1dff0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
1e000 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20  interface. ^The 
1e010 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1e020 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1e030 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
1e040 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
1e050 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
1e060 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
1e070 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
1e080 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
1e090 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69  orized. ^The thi
1e0a0 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
1e0b0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
1e0c0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
1e0d0 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
1e0e0 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
1e0f0 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e  contain addition
1e100 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62  al.** details ab
1e110 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
1e120 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
1e130 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^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 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
1e160 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
1e170 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1e180 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1e190 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
1e1a0 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
1e1b0 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
1e1c0 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
1e1d0 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
1e1e0 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
1e1f0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
1e200 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
1e210 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
1e220 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
1e230 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
1e240 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1e250 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
1e260 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
1e270 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
1e280 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
1e290 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
1e2a0 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20   of a table..** 
1e2b0 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
1e2c0 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  ode is [SQLITE_D
1e2d0 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63  ELETE] and the c
1e2e0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
1e2f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ** [SQLITE_IGNOR
1e300 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c  E] then the [DEL
1e310 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70  ETE] operation p
1e320 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a  roceeds but the.
1e330 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  ** [truncate opt
1e340 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69  imization] is di
1e350 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72  sabled and all r
1e360 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
1e370 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a  individually..**
1e380 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
1e390 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b  r is used when [
1e3a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
1e3b0 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20  | preparing].** 
1e3c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
1e3d0 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
1e3e0 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
1e3f0 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
1e400 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f  statements.** do
1e410 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
1e420 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65  ss data they are
1e430 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
1e440 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
1e450 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20  y do not.** try 
1e460 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  to execute malic
1e470 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
1e480 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
1e490 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
1e4a0 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
1e4b0 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
1e4c0 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
1e4d0 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
1e4e0 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
1e4f0 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
1e500 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
1e510 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1e520 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
1e530 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
1e540 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
1e550 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
1e560 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
1e570 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
1e580 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
1e590 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
1e5a0 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
1e5b0 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
1e5c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
1e5d0 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
1e5e0 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f   that.** disallo
1e5f0 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78  ws everything ex
1e600 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74  cept [SELECT] st
1e610 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
1e620 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
1e630 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73  t need to proces
1e640 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75  s SQL from untru
1e650 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20  sted sources.** 
1e660 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69  might also consi
1e670 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73  der lowering res
1e680 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69  ource limits usi
1e690 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
1e6a0 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69  t()].** and limi
1e6b0 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69  ting database si
1e6c0 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61  ze using the [ma
1e6d0 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
1e6e0 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64  RAGMA].** in add
1e6f0 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61  ition to using a
1e700 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  n authorizer..**
1e710 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e  .** ^(Only a sin
1e720 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
1e730 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
1e740 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
1e750 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
1e760 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
1e770 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
1e780 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
1e790 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
1e7a0 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44  ious call.)^  ^D
1e7b0 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
1e7c0 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
1e7d0 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
1e7e0 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
1e7f0 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
1e800 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
1e810 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
1e820 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
1e830 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
1e840 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
1e850 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
1e860 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1e870 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
1e880 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1e890 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
1e8a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e8b0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
1e8c0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
1e8d0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
1e8e0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1e8f0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
1e900 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
1e910 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
1e920 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  raph..**.** ^Whe
1e930 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
1e940 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64  re_v2()] is used
1e950 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74   to prepare a st
1e960 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20  atement, the.** 
1e970 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20  statement might 
1e980 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64  be re-prepared d
1e990 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
1e9a0 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
1e9b0 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
1e9c0 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
1e9d0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
1e9e0 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
1e9f0 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
1ea00 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ea10 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
1ea20 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
1ea30 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1ea40 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
1ea50 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1ea60 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1ea70 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
1ea80 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1ea90 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
1eaa0 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
1eab0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
1eac0 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
1ead0 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
1eae0 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
1eaf0 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73  3_step()], unles
1eb00 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69  s.** as stated i
1eb10 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
1eb20 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65  aragraph, sqlite
1eb30 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73  3_step() invokes
1eb40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
1eb50 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72  are_v2() to repr
1eb60 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1eb70 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61  t after a schema
1eb80 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20   change..*/.int 
1eb90 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1eba0 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
1ebb0 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
1ebc0 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
1ebd0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1ebe0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1ebf0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
1ec00 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
1ec10 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1ec20 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
1ec30 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
1ec40 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1ec50 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
1ec60 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1ec70 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
1ec80 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
1ec90 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
1eca0 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
1ecb0 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
1ecc0 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
1ecd0 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
1ece0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
1ecf0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
1ed00 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
1ed10 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1ed20 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1ed30 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
1ed40 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
1ed50 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1ed60 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  n..**.** Note th
1ed70 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  at SQLITE_IGNORE
1ed80 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73   is also used as
1ed90 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73   a [conflict res
1eda0 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a  olution mode].**
1edb0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74   returned from t
1edc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  he [sqlite3_vtab
1edd0 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
1ede0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64  interface..*/.#d
1edf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
1ee00 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
1ee10 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1ee20 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
1ee30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ee40 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
1ee50 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
1ee60 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
1ee70 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
1ee80 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
1ee90 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
1eea0 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Action Codes.**.
1eeb0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1eec0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1eed0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
1eee0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
1eef0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
1ef00 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
1ef10 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69  authorize certai
1ef20 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1ef30 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
1ef40 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1ef50 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
1ef60 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
1ef70 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
1ef80 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
1ef90 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
1efa0 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
1efb0 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
1efc0 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
1efd0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
1efe0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
1eff0 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
1f000 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
1f010 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
1f020 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
1f030 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
1f040 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e  e.** authorized.
1f050 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
1f060 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
1f070 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
1f080 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
1f090 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
1f0a0 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
1f0b0 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
1f0c0 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
1f0d0 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
1f0e0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1f0f0 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35  ameter.  ^(The 5
1f100 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1f110 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
1f120 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
1f130 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
1f140 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
1f150 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29  "temp",.** etc.)
1f160 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29   if applicable.)
1f170 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61  ^  ^The 6th para
1f180 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1f190 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1f1a0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
1f1b0 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
1f1c0 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
1f1d0 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
1f1e0 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
1f1f0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1f200 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
1f210 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
1f220 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
1f230 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
1f240 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   code..*/./*****
1f250 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f260 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f270 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
1f280 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
1f290 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
1f2a0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
1f2b0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
1f2c0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1f2d0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1f2e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f2f0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
1f300 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
1f310 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1f320 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f330 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f340 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1f350 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
1f360 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1f370 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1f380 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f390 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1f3a0 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
1f3b0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1f3c0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f3d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f3e0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1f3f0 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
1f400 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1f410 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f420 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f430 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
1f440 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
1f450 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1f460 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f470 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f480 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
1f490 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
1f4a0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1f4b0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1f4c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f4d0 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
1f4e0 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
1f4f0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1f500 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f510 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f520 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
1f530 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
1f540 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1f550 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f560 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1f570 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
1f580 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
1f590 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1f5a0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1f5b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1f5c0 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
1f5d0 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
1f5e0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1f5f0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f600 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1f610 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
1f620 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
1f630 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1f640 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1f650 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1f660 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1f670 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
1f680 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1f690 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f6a0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1f6b0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
1f6c0 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
1f6d0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1f6e0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1f6f0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1f700 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
1f710 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
1f720 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1f730 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f740 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
1f750 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
1f760 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1f770 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1f780 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f790 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
1f7a0 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
1f7b0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1f7c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f7d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f7e0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
1f7f0 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
1f800 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1f810 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f820 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f830 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
1f840 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
1f850 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
1f860 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
1f870 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
1f880 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
1f890 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
1f8a0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1f8b0 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
1f8c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f8d0 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
1f8e0 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
1f8f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f900 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f910 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f920 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
1f930 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
1f940 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
1f950 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f960 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f970 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
1f980 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
1f990 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
1f9a0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
1f9b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f9c0 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
1f9d0 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
1f9e0 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
1f9f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1fa00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fa10 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
1fa20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
1fa30 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
1fa40 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1fa50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1fa60 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
1fa70 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
1fa80 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
1fa90 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1faa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
1fab0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
1fac0 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
1fad0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1fae0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1faf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
1fb00 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
1fb10 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
1fb20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1fb30 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1fb40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1fb50 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
1fb60 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
1fb70 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
1fb80 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1fb90 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1fba0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
1fbb0 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
1fbc0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
1fbd0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1fbe0 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
1fbf0 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
1fc00 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
1fc10 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20         Function 
1fc20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e  Name   */.#defin
1fc30 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49  e SQLITE_SAVEPOI
1fc40 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32  NT            32
1fc50 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
1fc60 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20        Savepoint 
1fc70 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65  Name  */.#define
1fc80 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
1fc90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
1fca0 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
1fcb0 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  sed */.#define S
1fcc0 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20  QLITE_RECURSIVE 
1fcd0 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20             33   
1fce0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1fcf0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1fd00 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     */../*.** CAP
1fd10 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
1fd20 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
1fd30 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
1fd40 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
1fd50 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
1fd60 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
1fd70 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
1fd80 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
1fd90 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
1fda0 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
1fdb0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1fdc0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1fdd0 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1fde0 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
1fdf0 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
1fe00 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
1fe10 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
1fe20 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
1fe30 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
1fe40 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
1fe50 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1fe60 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1fe70 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
1fe80 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
1fe90 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
1fea0 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
1feb0 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
1fec0 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
1fed0 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
1fee0 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
1fef0 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
1ff00 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
1ff10 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
1ff20 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
1ff30 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
1ff40 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
1ff50 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
1ff60 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
1ff70 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
1ff80 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
1ff90 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
1ffa0 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
1ffb0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1ffc0 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
1ffd0 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68  d to limit.** th
1ffe0 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75  e length of [bou
1fff0 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78  nd parameter] ex
20000 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f  pansion in the o
20010 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33  utput of sqlite3
20020 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  _trace()..**.** 
20030 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
20040 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
20050 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
20060 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
20070 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
20080 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
20090 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
200a0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
200b0 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
200c0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
200d0 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
200e0 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
200f0 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
20100 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
20110 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
20120 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
20130 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
20140 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
20150 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
20160 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
20170 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
20180 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
20190 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
201a0 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
201b0 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
201c0 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
201d0 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
201e0 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
201f0 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
20200 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
20210 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
20220 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
20230 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
20240 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a  callback.  The.*
20250 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  * sqlite3_profil
20260 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
20270 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
20280 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a  imental and is.*
20290 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
202a0 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65  nge in future ve
202b0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
202c0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
202d0 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
202e0 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29  *, void(*xTrace)
202f0 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
20300 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
20310 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
20320 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70   void *sqlite3_p
20330 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
20340 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
20350 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
20360 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
20370 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
20380 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20390 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
203a0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
203b0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  The sqlite3_prog
203c0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e  ress_handler(D,N
203d0 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20  ,X,P) interface 
203e0 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
203f0 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
20400 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  X to be invoked 
20410 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
20420 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
20430 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
20440 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
20450 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
20460 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  and [sqlite3_get
20470 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a  _table()] for.**
20480 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20490 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d  tion D.  An exam
204a0 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
204b0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
204c0 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
204d0 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
204e0 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
204f0 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  ** ^The paramete
20500 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68  r P is passed th
20510 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c  rough as the onl
20520 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  y parameter to t
20530 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  he .** callback 
20540 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68  function X.  ^Th
20550 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73  e parameter N is
20560 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65   the approximate
20570 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b   number of .** [
20580 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
20590 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68  instructions] th
205a0 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  at are evaluated
205b0 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73   between success
205c0 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ive.** invocatio
205d0 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61  ns of the callba
205e0 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20  ck X.  ^If N is 
205f0 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68  less than one th
20600 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a  en the progress.
20610 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69  ** handler is di
20620 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  sabled..**.** ^O
20630 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f  nly a single pro
20640 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61  gress handler ma
20650 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20  y be defined at 
20660 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20  one time per.** 
20670 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
20680 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61  tion]; setting a
20690 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61   new progress ha
206a0 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68  ndler cancels th
206b0 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e  e.** old one.  ^
206c0 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65  Setting paramete
206d0 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61  r X to NULL disa
206e0 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73  bles the progres
206f0 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54  s handler..** ^T
20700 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
20710 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61  ler is also disa
20720 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20  bled by setting 
20730 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73  N to a value les
20740 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a  s.** than 1..**.
20750 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72  ** ^If the progr
20760 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
20770 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
20780 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
20790 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
207a0 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
207b0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
207c0 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
207d0 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
207e0 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69   GUI progress di
207f0 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
20800 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
20810 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  dler callback mu
20820 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
20830 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
20840 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
20850 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
20860 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
20870 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
20880 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
20890 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
208a0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
208b0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
208c0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
208d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
208e0 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
208f0 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
20900 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
20910 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73  ph..**.*/.void s
20920 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
20930 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
20940 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
20950 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
20960 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
20970 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
20980 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
20990 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
209a0 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
209b0 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
209c0 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64  ile as specified
209d0 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65   by the .** file
209e0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e  name argument. ^
209f0 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
20a00 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
20a10 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
20a20 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
20a30 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
20a40 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
20a50 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
20a60 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
20a70 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
20a80 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64  open16(). ^(A [d
20a90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20aa0 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
20ab0 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
20ac0 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
20ad0 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
20ae0 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
20af0 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
20b00 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
20b10 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
20b20 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
20b30 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
20b40 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
20b50 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
20b60 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
20b70 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
20b80 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
20b90 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e  e3].** object.)^
20ba0 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61   ^(If the databa
20bb0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
20bc0 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
20bd0 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
20be0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
20bf0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
20c00 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
20c10 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
20c20 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b  ned.)^ ^The.** [
20c30 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
20c40 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
20c50 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
20c60 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
20c70 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
20c80 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
20c90 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
20ca0 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69  he error followi
20cb0 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20  ng a failure of 
20cc0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  any.** of the sq
20cd0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75  lite3_open() rou
20ce0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tines..**.** ^Th
20cf0 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
20d00 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  ng will be UTF-8
20d10 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 63   for databases c
20d20 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
20d30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
20d40 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
20d50 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75  2().  ^The defau
20d60 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
20d70 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65  databases.** cre
20d80 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74  ated using sqlit
20d90 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c  e3_open16() will
20da0 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68   be UTF-16 in th
20db0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
20dc0 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  der..**.** Wheth
20dd0 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
20de0 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
20df0 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
20e00 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
20e10 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
20e20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20e30 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  on] handle shoul
20e40 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
20e50 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74  .** passing it t
20e60 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
20e70 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
20e80 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
20e90 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
20ea0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
20eb0 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
20ec0 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ike sqlite3_open
20ed0 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
20ee0 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f  t it accepts two
20ef0 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
20f00 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
20f10 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
20f20 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
20f30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20f40 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20  n.  ^(The flags 
20f50 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
20f60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
20f70 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  ) can take one o
20f80 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
20f90 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
20fa0 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
20fb0 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
20fc0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
20fd0 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
20fe0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
20ff0 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  , [SQLITE_OPEN_S
21000 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20  HAREDCACHE],.** 
21010 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
21020 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f  VATECACHE], and/
21030 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
21040 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a  URI] flags:)^.**
21050 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64  .** <dl>.** ^(<d
21060 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
21070 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a  EADONLY]</dt>.**
21080 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
21090 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72  e is opened in r
210a0 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20  ead-only mode.  
210b0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
210c0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65  does not.** alre
210d0 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  ady exist, an er
210e0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
210f0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
21100 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
21110 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e  _READWRITE]</dt>
21120 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
21130 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
21140 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
21150 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
21160 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a  le, or reading.*
21170 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69  * only if the fi
21180 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
21190 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
211a0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
211b0 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73  In either.** cas
211c0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  e the database m
211d0 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
211e0 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  t, otherwise an 
211f0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
21200 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
21210 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
21220 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
21230 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
21240 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATE]</dt>.** <dd
21250 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
21260 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
21270 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c  ing and writing,
21280 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20   and is created 
21290 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
212a0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
212b0 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68   This is the beh
212c0 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
212d0 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a  ways used for.**
212e0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
212f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
21300 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  16().</dd>)^.** 
21310 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  </dl>.**.** If t
21320 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
21330 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
21340 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  _v2() is not one
21350 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69   of the.** combi
21360 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
21370 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  ove optionally c
21380 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68  ombined with oth
21390 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  er.** [SQLITE_OP
213a0 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51  EN_READONLY | SQ
213b0 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73  LITE_OPEN_* bits
213c0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ].** then the be
213d0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
213e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
213f0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
21400 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  NOMUTEX] flag is
21410 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64   set, then the d
21420 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21430 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74  on.** opens in t
21440 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20  he multi-thread 
21450 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
21460 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
21470 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a  single-thread.**
21480 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65   mode has not be
21490 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  en set at compil
214a0 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
214b0 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a  time.  ^If the.*
214c0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  * [SQLITE_OPEN_F
214d0 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  ULLMUTEX] flag i
214e0 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64  s set then the d
214f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21500 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74  on opens.** in t
21510 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
21520 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75  hreading mode] u
21530 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72  nless single-thr
21540 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  ead was.** previ
21550 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61  ously selected a
21560 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
21570 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a  r start-time..**
21580 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
21590 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20  EN_SHAREDCACHE] 
215a0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
215b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
215c0 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69  ion to be.** eli
215d0 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68  gible to use [sh
215e0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
215f0 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
21600 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
21610 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69  hared.** cache i
21620 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  s enabled using 
21630 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
21640 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e  shared_cache()].
21650 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54    ^The.** [SQLIT
21660 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
21670 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
21680 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
21690 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a  nnection to not.
216a0 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69  ** participate i
216b0 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  n [shared cache 
216c0 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74  mode] even if it
216d0 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
216e0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
216f0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
21700 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
21710 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
21720 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
21730 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
21740 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74  fines the operat
21750 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
21760 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  face that.** the
21770 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
21780 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  nnection should 
21790 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f  use.  ^If the fo
217a0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
217b0 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
217c0 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
217d0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
217e0 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
217f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
21800 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
21810 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20  emory:", then a 
21820 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
21830 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ry in-memory dat
21840 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61  abase.** is crea
21850 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
21860 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69  ection.  ^This i
21870 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
21880 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68  e will vanish wh
21890 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  en.** the databa
218a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
218b0 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
218c0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
218d0 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b  ite might.** mak
218e0 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
218f0 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
21900 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e  names that begin
21910 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
21920 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69  aracter..** It i
21930 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
21940 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  at when a databa
21950 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75  se filename actu
21960 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
21970 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68  with.** a ":" ch
21980 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75  aracter you shou
21990 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ld prefix the fi
219a0 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
219b0 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a  thname such as.*
219c0 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20  * "./" to avoid 
219d0 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
219e0 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
219f0 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
21a00 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
21a10 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a  vate, temporary.
21a20 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  ** on-disk datab
21a30 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
21a40 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76  ted.  ^This priv
21a50 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
21a60 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
21a70 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
21a80 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
21a90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21aa0 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
21ab0 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
21ac0 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65  s in sqlite3_ope
21ad0 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69  n()]] <h3>URI Fi
21ae0 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  lenames</h3>.**.
21af0 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65  ** ^If [URI file
21b00 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61  name] interpreta
21b10 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c  tion is enabled,
21b20 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d   and the filenam
21b30 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65  e argument.** be
21b40 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a  gins with "file:
21b50 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65  ", then the file
21b60 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65  name is interpre
21b70 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55  ted as a URI. ^U
21b80 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  RI.** filename i
21b90 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
21ba0 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
21bb0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
21bc0 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74  ] flag is.** set
21bd0 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61   in the fourth a
21be0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
21bf0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72  e3_open_v2(), or
21c00 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65   if it has.** be
21c10 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61  en enabled globa
21c20 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53  lly using the [S
21c30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
21c40 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68  ] option with th
21c50 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
21c60 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f  nfig()] method o
21c70 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  r by the [SQLITE
21c80 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c  _USE_URI] compil
21c90 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
21ca0 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76  * As of SQLite v
21cb0 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52  ersion 3.7.7, UR
21cc0 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  I filename inter
21cd0 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72  pretation is tur
21ce0 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65  ned off.** by de
21cf0 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72  fault, but futur
21d00 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
21d10 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c  Lite might enabl
21d20 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a  e URI filename.*
21d30 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  * interpretation
21d40 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65   by default.  Se
21d50 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  e "[URI filename
21d60 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  s]" for addition
21d70 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
21d80 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c  n..**.** URI fil
21d90 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65  enames are parse
21da0 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52  d according to R
21db0 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65  FC 3986. ^If the
21dc0 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e   URI contains an
21dd0 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74  .** authority, t
21de0 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65  hen it must be e
21df0 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73  ither an empty s
21e00 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72  tring or the str
21e10 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f  ing .** "localho
21e20 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74  st". ^If the aut
21e30 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e  hority is not an
21e40 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
21e50 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e   "localhost", an
21e60 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65   .** error is re
21e70 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61  turned to the ca
21e80 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d  ller. ^The fragm
21e90 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ent component of
21ea0 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70   a URI, if .** p
21eb0 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72  resent, is ignor
21ec0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ed..**.** ^SQLit
21ed0 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20  e uses the path 
21ee0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65  component of the
21ef0 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65   URI as the name
21f00 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c   of the disk fil
21f10 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61  e.** which conta
21f20 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ins the database
21f30 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62  . ^If the path b
21f40 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27  egins with a '/'
21f50 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20   character, .** 
21f60 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72  then it is inter
21f70 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73  preted as an abs
21f80 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20  olute path. ^If 
21f90 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f  the path does no
21fa0 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68  t begin .** with
21fb0 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20   a '/' (meaning 
21fc0 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
21fd0 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d  ty section is om
21fe0 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55  itted from the U
21ff0 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  RI).** then the 
22000 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65  path is interpre
22010 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76  ted as a relativ
22020 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e  e path. .** ^(On
22030 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69   windows, the fi
22040 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  rst component of
22050 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
22060 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65  h .** is a drive
22070 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28   specification (
22080 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a  e.g. "C:").)^.**
22090 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71  .** [[core URI q
220a0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d  uery parameters]
220b0 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63  ].** The query c
220c0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
220d0 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61  I may contain pa
220e0 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72  rameters that ar
220f0 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a  e interpreted.**
22100 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74   either by SQLit
22110 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20  e itself, or by 
22120 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20  a [VFS | custom 
22130 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
22140 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61  on]..** SQLite a
22150 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20  nd its built-in 
22160 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65  [VFSes] interpre
22170 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  t the.** followi
22180 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ng query paramet
22190 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ers:.**.** <ul>.
221a0 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73  **   <li> <b>vfs
221b0 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22  </b>: ^The "vfs"
221c0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
221d0 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66  e used to specif
221e0 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a  y the name of.**
221f0 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63       a VFS objec
22200 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20  t that provides 
22210 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
22220 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
22230 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20  hat should.**   
22240 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63    be used to acc
22250 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
22260 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e   file on disk. ^
22270 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  If this option i
22280 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20  s set to.**     
22290 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
222a0 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
222b0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20  object is used. 
222c0 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
222d0 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46  nknown.**     VF
222e0 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e  S is an error. ^
222f0 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
22300 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
22310 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20   the vfs option 
22320 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e  is.**     presen
22330 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20  t, then the VFS 
22340 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
22350 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72   option takes pr
22360 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a  ecedence over.**
22370 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70       the value p
22380 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75  assed as the fou
22390 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
223a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
223b0 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
223c0 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28   <b>mode</b>: ^(
223d0 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  The mode paramet
223e0 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
223f0 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72   either "ro", "r
22400 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22  w",.**     "rwc"
22410 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41  , or "memory". A
22420 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74  ttempting to set
22430 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72   it to any other
22440 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20   value is.**    
22450 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a   an error)^. .**
22460 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73       ^If "ro" is
22470 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e   specified, then
22480 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
22490 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
224a0 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63  -only .**     ac
224b0 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66  cess, just as if
224c0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
224d0 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67  N_READONLY] flag
224e0 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e   had been set in
224f0 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69   the .**     thi
22500 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
22510 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
22520 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f  . ^If the mode o
22530 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20  ption is set to 
22540 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68  .**     "rw", th
22550 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
22560 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
22570 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f  ad-write (but no
22580 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20  t create) .**   
22590 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20    access, as if 
225a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
225b0 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53  WRITE (but not S
225c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
225d0 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62  E) had .**     b
225e0 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20  een set. ^Value 
225f0 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c  "rwc" is equival
22600 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62  ent to setting b
22610 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49  oth .**     SQLI
22620 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
22630 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45  E and SQLITE_OPE
22640 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74  N_CREATE.  ^If t
22650 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
22660 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20  s.**     set to 
22670 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20  "memory" then a 
22680 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20  pure [in-memory 
22690 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e  database] that n
226a0 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20  ever reads.**   
226b0 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d    or writes from
226c0 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e   disk is used. ^
226d0 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74  It is an error t
226e0 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75  o specify a valu
226f0 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65  e for.**     the
22700 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
22710 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73  that is less res
22720 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68  trictive than th
22730 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a  at specified by.
22740 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73  **     the flags
22750 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74   passed in the t
22760 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
22770 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
22780 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
22790 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20  > <b>cache</b>: 
227a0 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d  ^The cache param
227b0 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
227c0 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65  to either "share
227d0 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72  d" or.**     "pr
227e0 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67  ivate". ^Setting
227f0 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20   it to "shared" 
22800 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
22810 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20   setting the.** 
22820 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
22830 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20  SHAREDCACHE bit 
22840 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  in the flags arg
22850 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a  ument passed to.
22860 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f  **     sqlite3_o
22870 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69  pen_v2(). ^Setti
22880 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72  ng the cache par
22890 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61  ameter to "priva
228a0 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65  te" is .**     e
228b0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
228c0 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  ting the SQLITE_
228d0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
228e0 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49  E bit..**     ^I
228f0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
22900 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
22910 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61  the "cache" para
22920 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74  meter is present
22930 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49   in.**     a URI
22940 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76   filename, its v
22950 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61  alue overrides a
22960 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75  ny behavior requ
22970 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67  ested by setting
22980 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
22990 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
229a0 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   or SQLITE_OPEN_
229b0 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67  SHAREDCACHE flag
229c0 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
229d0 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20  >psow</b>: ^The 
229e0 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69  psow parameter i
229f0 6e 64 69 63 61 74 65 73 20 77 68 65 74 68 65 72  ndicates whether
22a00 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20   or not the.**  
22a10 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76     [powersafe ov
22a20 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74  erwrite] propert
22a30 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e  y does or does n
22a40 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a  ot apply to the.
22a50 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d  **     storage m
22a60 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68  edia on which th
22a70 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
22a80 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20  resides..**.**  
22a90 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f  <li> <b>nolock</
22aa0 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20  b>: ^The nolock 
22ab0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
22ac0 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72  oolean query par
22ad0 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68  ameter.**     wh
22ae0 69 63 68 20 69 66 20 73 65 74 20 64 69 73 61 62  ich if set disab
22af0 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67  les file locking
22b00 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75   in rollback jou
22b10 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69  rnal modes.  Thi
22b20 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66  s.**     is usef
22b30 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67  ul for accessing
22b40 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61   a database on a
22b50 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74   filesystem that
22b60 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20   does not.**    
22b70 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67   support locking
22b80 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74  .  Caution:  Dat
22b90 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
22ba0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
22bb0 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d   two.**     or m
22bc0 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20 77 72  ore processes wr
22bd0 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20  ite to the same 
22be0 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79  database and any
22bf0 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a   one of those.**
22c00 20 20 20 20 20 70 72 6f 63 65 73 73 65 73 20 75       processes u
22c10 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a  ses nolock=1..**
22c20 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d  .**  <li> <b>imm
22c30 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65  utable</b>: ^The
22c40 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d   immutable param
22c50 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61  eter is a boolea
22c60 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70  n query.**     p
22c70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e  arameter that in
22c80 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65  dicates that the
22c90 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
22ca0 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20  s stored on.**  
22cb0 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64     read-only med
22cc0 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74  ia.  ^When immut
22cd0 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c  able is set, SQL
22ce0 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
22cf0 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61   the.**     data
22d00 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74  base file cannot
22d10 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65   be changed, eve
22d20 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73 20 77  n by a process w
22d30 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20  ith higher.**   
22d40 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64    privilege, and
22d50 20 73 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   so the database
22d60 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d   is opened read-
22d70 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63  only and all loc
22d80 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20  king.**     and 
22d90 63 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e  change detection
22da0 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43   is disabled.  C
22db0 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20  aution: Setting 
22dc0 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a  the immutable.**
22dd0 20 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e       property on
22de0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
22df0 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61   that does in fa
22e00 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65  ct change can re
22e10 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69  sult.**     in i
22e20 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79 20 72  ncorrect query r
22e30 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53  esults and/or [S
22e40 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65  QLITE_CORRUPT] e
22e50 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65  rrors..**     Se
22e60 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f  e also: [SQLITE_
22e70 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d  IOCAP_IMMUTABLE]
22e80 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c  ..**       .** <
22e90 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63  /ul>.**.** ^Spec
22ea0 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
22eb0 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  n parameter in t
22ec0 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
22ed0 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e  nt of a URI is n
22ee0 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20  ot an.** error. 
22ef0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
22f00 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
22f10 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69   understand addi
22f20 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20  tional query.** 
22f30 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65  parameters.  See
22f40 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74   "[query paramet
22f50 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c  ers with special
22f60 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69   meaning to SQLi
22f70 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69  te]" for.** addi
22f80 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
22f90 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  on..**.** [[URI 
22fa0 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
22fb0 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65  s]] <h3>URI file
22fc0 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68  name examples</h
22fd0 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20  3>.**.** <table 
22fe0 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e  border="1" align
22ff0 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64  =center cellpadd
23000 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  ing=5>.** <tr><t
23010 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  h> URI filenames
23020 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a   <th> Results.**
23030 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
23040 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
23050 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
23060 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
23070 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
23080 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74  directory..** <t
23090 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
230a0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62  e/fred/data.db<b
230b0 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  r>.**          f
230c0 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64  ile:///home/fred
230d0 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a  /data.db <br> .*
230e0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
230f0 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65  //localhost/home
23100 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
23110 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  r> <td> .**     
23120 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61       Open the da
23130 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f  tabase file "/ho
23140 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
23150 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
23160 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f  le://darkstar/ho
23170 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
23180 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
23190 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72    An error. "dar
231a0 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20  kstar" is not a 
231b0 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f  recognized autho
231c0 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  rity..** <tr><td
231d0 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70   style="white-sp
231e0 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a  ace:nowrap"> .**
231f0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
23200 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32  //C:/Documents%2
23210 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f  0and%20Settings/
23220 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74  fred/Desktop/dat
23230 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e  a.db.**     <td>
23240 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f   Windows only: O
23250 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
23260 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73  ta.db" on fred's
23270 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76   desktop on driv
23280 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a  e.**          C:
23290 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
232a0 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20  %20 escaping in 
232b0 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20  this example is 
232c0 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a  not strictly .**
232d0 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73            necess
232e0 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72  ary - space char
232f0 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73  acters can be us
23300 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20  ed literally.** 
23310 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20           in URI 
23320 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74  filenames..** <t
23330 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
23340 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68  .db?mode=ro&cach
23350 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a  e=private <td> .
23360 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
23370 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
23380 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
23390 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61  irectory for rea
233a0 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a  d-only access..*
233b0 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72  *          Regar
233c0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
233d0 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63   or not shared-c
233e0 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61  ache mode is ena
233f0 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  bled by.**      
23400 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65      default, use
23410 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65   a private cache
23420 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
23430 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
23440 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64  ta.db?vfs=unix-d
23450 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20  otfile <td>.**  
23460 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
23470 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  e "/home/fred/da
23480 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20  ta.db". Use the 
23490 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69  special VFS "uni
234a0 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20  x-dotfile".**   
234b0 20 20 20 20 20 20 20 74 68 61 74 20 75 73 65 73         that uses
234c0 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c   dot-files in pl
234d0 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76  ace of posix adv
234e0 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a  isory locking..*
234f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
23500 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61  data.db?mode=rea
23510 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20  donly <td> .**  
23520 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72          An error
23530 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20  . "readonly" is 
23540 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69  not a valid opti
23550 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65  on for the "mode
23560 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  " parameter..** 
23570 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e  </table>.**.** ^
23580 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20  URI hexadecimal 
23590 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
235a0 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f   (%HH) are suppo
235b0 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20  rted within the 
235c0 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72  path and.** quer
235d0 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
235e0 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63  a URI. A hexadec
235f0 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
23600 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66  ence consists of
23610 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69   a.** percent si
23620 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f  gn - "%" - follo
23630 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74  wed by exactly t
23640 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  wo hexadecimal d
23650 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66  igits .** specif
23660 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61  ying an octet va
23670 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65  lue. ^Before the
23680 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63   path or query c
23690 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a  omponents of a.*
236a0 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61  * URI filename a
236b0 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20  re interpreted, 
236c0 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64  they are encoded
236d0 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64   using UTF-8 and
236e0 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63   all .** hexadec
236f0 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
23700 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62  ences replaced b
23710 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20  y a single byte 
23720 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a  containing the.*
23730 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  * corresponding 
23740 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70  octet. If this p
23750 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73  rocess generates
23760 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d   an invalid UTF-
23770 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74  8 encoding,.** t
23780 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
23790 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
237a0 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
237b0 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  ws users:</b>  T
237c0 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  he encoding used
237d0 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d   for the filenam
237e0 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66  e argument.** of
237f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
23800 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
23810 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54  _v2() must be UT
23820 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65  F-8, not whateve
23830 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73  r.** codepage is
23840 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
23850 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63  ed.  Filenames c
23860 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e  ontaining intern
23870 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61  ational.** chara
23880 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f  cters must be co
23890 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38  nverted to UTF-8
238a0 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e   prior to passin
238b0 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73  g them into.** s
238c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
238d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
238e0 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ()..**.** <b>Not
238f0 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e  e to Windows Run
23900 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20  time users:</b> 
23910 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64   The temporary d
23920 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65  irectory must be
23930 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f   set.** prior to
23940 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   calling sqlite3
23950 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
23960 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f  e3_open_v2().  O
23970 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75  therwise, variou
23980 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68  s.** features th
23990 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75  at require the u
239a0 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20  se of temporary 
239b0 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a  files may fail..
239c0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
239d0 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  [sqlite3_temp_di
239e0 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20  rectory].*/.int 
239f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
23a00 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
23a10 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
23a20 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
23a30 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
23a40 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
23a50 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
23a60 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
23a70 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
23a80 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
23a90 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
23aa0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
23ab0 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
23ac0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
23ad0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
23ae0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
23af0 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
23b00 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
23b10 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
23b20 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
23b30 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
23b40 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
23b50 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
23b60 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
23b70 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
23b80 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
23b90 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
23ba0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
23bb0 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
23bc0 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
23bd0 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
23be0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23bf0 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20  : Obtain Values 
23c00 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65  For URI Paramete
23c10 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  rs.**.** These a
23c20 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69  re utility routi
23c30 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56  nes, useful to V
23c40 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
23c50 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a  ns, that check.*
23c60 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61  * to see if a da
23c70 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20  tabase file was 
23c80 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61  a URI that conta
23c90 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20  ined a specific 
23ca0 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65  query .** parame
23cb0 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f  ter, and if so o
23cc0 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65  btains the value
23cd0 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70   of that query p
23ce0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
23cf0 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61  If F is the data
23d00 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f  base filename po
23d10 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74  inter passed int
23d20 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65  o the xOpen() me
23d30 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46  thod of .** a VF
23d40 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
23d50 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20   when the flags 
23d60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
23d70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20  en() has one or 
23d80 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20  .** more of the 
23d90 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
23da0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ] or [SQLITE_OPE
23db0 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20  N_MAIN_DB] bits 
23dc0 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20  set and.** P is 
23dd0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
23de0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c  query parameter,
23df0 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
23e00 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
23e10 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  ,P) returns the 
23e20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a  value of the P.*
23e30 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69  * parameter if i
23e40 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55  t exists or a NU
23e50 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20  LL pointer if P 
23e60 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20  does not appear 
23e70 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70  as a .** query p
23e80 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20  arameter on F.  
23e90 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20  If P is a query 
23ea0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a  parameter of F.*
23eb0 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69  * has no explici
23ec0 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71  t value, then sq
23ed0 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
23ee0 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
23ef0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
23f00 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
23f10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
23f20 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
23f30 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61  F,P,B) routine a
23f40 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73  ssumes that P is
23f50 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61   a boolean.** pa
23f60 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
23f70 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20  rns true (1) or 
23f80 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64  false (0) accord
23f90 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ing to the value
23fa0 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73  .** of P.  The s
23fb0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
23fc0 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
23fd0 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
23fe0 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c  1) if the.** val
23ff0 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61  ue of query para
24000 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
24010 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c  f "yes", "true",
24020 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a   or "on" in any.
24030 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68  ** case or if th
24040 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
24050 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e  ith a non-zero n
24060 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20  umber.  The .** 
24070 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
24080 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
24090 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73  nes returns fals
240a0 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c  e (0) if the val
240b0 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70  ue of.** query p
240c0 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
240d0 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73  e of "no", "fals
240e0 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20  e", or "off" in 
240f0 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69  any case or.** i
24100 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
24110 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69  ns with a numeri
24120 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73  c zero.  If P is
24130 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20   not a query.** 
24140 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f  parameter on F o
24150 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  r if the value o
24160 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20  f P is does not 
24170 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65  match any of the
24180 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20  .** above, then 
24190 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
241a0 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
241b0 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a  ns (B!=0)..**.**
241c0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
241d0 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f  _int64(F,P,D) ro
241e0 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74  utine converts t
241f0 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e  he value of P in
24200 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73  to a.** 64-bit s
24210 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
24220 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69  d returns that i
24230 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20  nteger, or D if 
24240 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78  P does not.** ex
24250 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c  ist.  If the val
24260 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74  ue of P is somet
24270 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
24280 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e  an integer, then
24290 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75  .** zero is retu
242a0 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20  rned..** .** If 
242b0 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  F is a NULL poin
242c0 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ter, then sqlite
242d0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
242e0 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  F,P) returns NUL
242f0 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  L and.** sqlite3
24300 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
24310 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20  ,B) returns B.  
24320 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55  If F is not a NU
24330 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a  LL pointer and.*
24340 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  * is not a datab
24350 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  ase file pathnam
24360 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53  e pointer that S
24370 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74  QLite passed int
24380 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56  o the xOpen.** V
24390 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  FS method, then 
243a0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
243b0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
243c0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
243d0 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69  obably.** undesi
243e0 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  rable..*/.const 
243f0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72  char *sqlite3_ur
24400 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73  i_parameter(cons
24410 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
24420 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
24430 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69  Param);.int sqli
24440 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
24450 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
24460 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
24470 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61  Param, int bDefa
24480 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ult);.sqlite3_in
24490 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  t64 sqlite3_uri_
244a0 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72  int64(const char
244b0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
244c0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
244d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
244e0 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
244f0 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a  d Messages.**.**
24500 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
24510 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63  rcode() interfac
24520 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
24530 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
24540 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
24550 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
24560 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
24570 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69  cent failed sqli
24580 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a  te3_* API call.*
24590 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
245a0 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
245b0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20  nnection]. If a 
245c0 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66  prior API call f
245d0 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65  ailed.** but the
245e0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
245f0 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c   call succeeded,
24600 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
24610 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  e from.** sqlite
24620 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
24630 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  ndefined.  ^The 
24640 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
24650 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
24660 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
24670 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
24680 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
24690 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
246a0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
246b0 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
246c0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
246d0 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
246e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
246f0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
24700 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
24710 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
24720 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
24730 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
24740 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
24750 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
24760 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
24770 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
24780 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
24790 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
247a0 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
247b0 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
247c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
247d0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
247e0 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
247f0 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
24800 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
24810 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
24820 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
24830 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
24840 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
24850 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
24860 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
24870 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
24880 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
24890 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66  _errstr() interf
248a0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
248b0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
248c0 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65   text.** that de
248d0 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73  scribes the [res
248e0 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54  ult code], as UT
248f0 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  F-8..** ^(Memory
24900 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
24910 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
24920 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
24930 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d  ernally.** and m
24940 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64  ust not be freed
24950 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
24960 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ion)^..**.** Whe
24970 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
24980 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
24990 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
249a0 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
249b0 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
249c0 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
249d0 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
249e0 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
249f0 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
24a00 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
24a10 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
24a20 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
24a30 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
24a40 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
24a50 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
24a60 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
24a70 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
24a80 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
24a90 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
24aa0 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
24ab0 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
24ac0 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
24ad0 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
24ae0 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
24af0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
24b00 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
24b10 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
24b20 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
24b30 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
24b40 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
24b50 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
24b60 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
24b70 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
24b80 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
24b90 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
24ba0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
24bb0 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
24bc0 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
24bd0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
24be0 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
24bf0 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
24c00 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
24c10 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
24c20 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
24c30 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
24c40 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
24c50 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
24c60 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
24c70 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
24c80 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
24c90 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
24ca0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
24cb0 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  b);.int sqlite3_
24cc0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
24cd0 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63  (sqlite3 *db);.c
24ce0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
24cf0 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
24d00 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  3*);.const void 
24d10 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
24d20 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  6(sqlite3*);.con
24d30 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
24d40 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f  _errstr(int);../
24d50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
24d60 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
24d70 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
24d80 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
24d90 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
24da0 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
24db0 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
24dc0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
24dd0 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
24de0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
24df0 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
24e00 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
24e10 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
24e20 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
24e30 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
24e40 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
24e50 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
24e60 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
24e70 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
24e80 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
24e90 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
24ea0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
24eb0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
24ec0 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
24ed0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
24ee0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
24ef0 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
24f00 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
24f10 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
24f20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
24f30 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
24f40 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
24f50 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
24f60 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
24f70 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
24f80 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
24f90 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
24fa0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
24fb0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
24fc0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
24fd0 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
24fe0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
24ff0 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
25000 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
25010 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
25020 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
25030 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
25040 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
25050 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
25060 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
25070 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
25080 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
25090 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
250a0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
250b0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
250c0 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
250d0 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
250e0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
250f0 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a  ime Limits.**.**
25100 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
25110 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
25120 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
25130 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
25140 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
25150 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
25160 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
25170 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
25180 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
25190 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
251a0 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
251b0 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
251c0 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
251d0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
251e0 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
251f0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
25200 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
25210 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
25220 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
25230 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
25240 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
25250 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
25260 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
25270 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
25280 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
25290 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
252a0 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
252b0 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
252c0 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
252d0 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
252e0 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
252f0 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
25300 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
25310 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
25320 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
25330 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
25340 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
25350 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
25360 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
25370 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
25380 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
25390 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
253a0 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
253b0 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
253c0 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
253d0 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
253e0 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
253f0 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
25400 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
25410 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
25420 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
25430 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
25440 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
25450 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
25460 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
25470 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
25480 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
25490 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
254a0 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
254b0 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
254c0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
254d0 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
254e0 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
254f0 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
25500 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
25510 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
25520 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
25530 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
25540 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
25550 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
25560 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
25570 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
25580 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
25590 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
255a0 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
255b0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
255c0 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
255d0 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
255e0 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
255f0 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
25600 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
25610 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
25620 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
25630 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
25640 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
25650 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
25660 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
25670 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
25680 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
25690 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
256a0 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
256b0 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
256c0 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
256d0 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
256e0 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
256f0 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
25700 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
25710 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
25720 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
25730 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
25740 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
25750 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
25760 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
25770 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
25780 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
25790 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
257a0 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
257b0 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
257c0 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
257d0 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
257e0 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
257f0 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
25800 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
25810 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
25820 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
25830 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
25840 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
25850 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
25860 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
25870 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
25880 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
25890 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ses..*/.int sqli
258a0 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
258b0 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
258c0 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
258d0 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
258e0 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
258f0 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
25900 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
25910 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
25920 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
25930 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
25940 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
25950 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
25960 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
25970 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
25980 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
25990 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
259a0 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
259b0 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
259c0 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
259d0 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
259e0 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
259f0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
25a00 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
25a10 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
25a20 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
25a30 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  >.** [[SQLITE_LI
25a40 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  MIT_LENGTH]] ^(<
25a50 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
25a60 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
25a70 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
25a80 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
25a90 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
25aa0 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73  le row, in bytes
25ab0 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  .<dd>)^.**.** [[
25ac0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
25ad0 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
25ae0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
25af0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
25b00 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
25b10 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
25b20 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
25b30 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
25b40 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
25b50 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74  T_COLUMN]] ^(<dt
25b60 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
25b70 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
25b80 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
25b90 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
25ba0 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
25bb0 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
25bc0 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
25bd0 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
25be0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
25bf0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
25c00 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
25c10 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
25c20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
25c30 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
25c40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
25c50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
25c60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
25c70 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
25c80 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
25c90 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
25ca0 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
25cb0 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29  xpression.</dd>)
25cc0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
25cd0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
25ce0 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53  SELECT]] ^(<dt>S
25cf0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
25d00 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
25d10 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
25d20 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
25d30 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
25d40 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
25d50 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
25d60 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
25d70 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e  VDBE_OP]] ^(<dt>
25d80 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
25d90 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
25da0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
25db0 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
25dc0 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
25dd0 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
25de0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
25df0 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
25e00 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69  tement.  This li
25e10 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65  mit is not curre
25e20 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64  ntly.** enforced
25e30 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69  , though that mi
25e40 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20  ght be added in 
25e50 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
25e60 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
25e70 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
25e80 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
25e90 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c  NCTION_ARG]] ^(<
25ea0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
25eb0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74  FUNCTION_ARG</dt
25ec0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
25ed0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
25ee0 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75  rguments on a fu
25ef0 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  nction.</dd>)^.*
25f00 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25f10 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e  MIT_ATTACHED]] ^
25f20 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
25f30 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
25f40 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
25f50 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54  um number of [AT
25f60 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20  TACH | attached 
25f70 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64  databases].)^</d
25f80 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
25f90 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
25fa0 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a  TERN_LENGTH]].**
25fb0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25fc0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
25fd0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
25fe0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
25ff0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
26000 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
26010 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a  o the [LIKE] or.
26020 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  ** [GLOB] operat
26030 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ors.</dd>)^.**.*
26040 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
26050 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
26060 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
26070 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
26080 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
26090 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
260a0 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66   index number of
260b0 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d   any [parameter]
260c0 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
260d0 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ment.)^.**.** [[
260e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
260f0 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  GGER_DEPTH]] ^(<
26100 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26110 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64  TRIGGER_DEPTH</d
26120 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
26130 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72  ximum depth of r
26140 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69  ecursion for tri
26150 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ggers.</dd>)^.**
26160 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
26170 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
26180 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  S]] ^(<dt>SQLITE
26190 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
261a0 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  READS</dt>.** <d
261b0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
261c0 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72  mber of auxiliar
261d0 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73  y worker threads
261e0 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a   that a single.*
261f0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
26200 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74  ement] may start
26210 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
26220 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
26230 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
26240 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26250 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
26260 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
26270 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
26280 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
26290 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
262a0 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
262b0 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
262c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
262d0 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
262e0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
262f0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
26300 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
26310 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
26320 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
26330 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
26340 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
26350 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
26360 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
26370 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
26380 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
26390 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
263a0 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
263b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
263c0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
263d0 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
263e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
263f0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
26400 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
26410 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
26420 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
26430 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
26440 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
26450 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
26460 41 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31  ADS           11
26470 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26480 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
26490 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
264a0 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
264b0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
264c0 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
264d0 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
264e0 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
264f0 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
26500 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
26510 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
26520 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
26530 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
26540 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
26550 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
26560 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
26570 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
26580 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
26590 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
265a0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
265b0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
265c0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
265d0 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
265e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
265f0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
26600 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
26610 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
26620 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
26630 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
26640 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
26650 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
26660 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
26670 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
26680 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
26690 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
266a0 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
266b0 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
266c0 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
266d0 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
266e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
266f0 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
26700 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
26710 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
26720 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  t is less than z
26730 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
26740 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
26750 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
26760 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
26770 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
26780 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
26790 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
267a0 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73  number of  bytes
267b0 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
267c0 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73    ^When nByte is
267d0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
267e0 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
267f0 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
26800 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
26810 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
26820 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
26830 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
26840 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
26850 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
26860 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
26870 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
26880 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
26890 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
268a0 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
268b0 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
268c0 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
268d0 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
268e0 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
268f0 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
26900 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
26910 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
26920 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
26930 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
26940 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
26950 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73  minator bytes as
26960 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69   this saves SQLi
26970 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74  te from having t
26980 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79  o.** make a copy
26990 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   of the input st
269a0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ring..**.** ^If 
269b0 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
269c0 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
269d0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
269e0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
269f0 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
26a00 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
26a10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
26a20 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
26a30 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
26a40 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
26a50 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
26a60 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
26a70 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
26a80 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
26a90 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
26aa0 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
26ab0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
26ac0 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
26ad0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26ae0 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
26af0 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
26b00 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
26b10 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
26b20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
26b30 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
26b40 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
26b50 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
26b60 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
26b70 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
26b80 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
26b90 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
26ba0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
26bb0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
26bc0 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
26bd0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
26be0 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
26bf0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
26c00 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
26c10 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
26c20 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
26c30 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
26c40 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
26c50 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
26c60 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
26c70 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
26c80 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
26c90 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
26ca0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
26cb0 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
26cc0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
26cd0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
26ce0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
26cf0 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
26d00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
26d10 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
26d20 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
26d30 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
26d40 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
26d50 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
26d60 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
26d70 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
26d80 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
26d90 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
26da0 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
26db0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
26dc0 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
26dd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
26de0 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
26df0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
26e00 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
26e10 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
26e20 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
26e30 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
26e40 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
26e50 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
26e60 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
26e70 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
26e80 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
26e90 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
26ea0 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
26eb0 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
26ec0 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
26ed0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
26ee0 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
26ef0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
26f00 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
26f10 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
26f20 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
26f30 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
26f40 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
26f50 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
26f60 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53  n. As many as [S
26f70 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41  QLITE_MAX_SCHEMA
26f80 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69  _RETRY].** retri
26f90 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65  es will occur be
26fa0 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65  fore sqlite3_ste
26fb0 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64  p() gives up and
26fc0 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f   returns an erro
26fd0 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  r..** </li>.**.*
26fe0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
26ff0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
27000 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
27010 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
27020 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
27030 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
27040 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
27050 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
27060 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
27070 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
27080 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
27090 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
270a0 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
270b0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
270c0 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
270d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
270e0 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
270f0 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
27100 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
27110 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
27120 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
27130 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
27140 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
27150 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
27160 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
27170 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
27180 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
27190 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
271a0 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
271b0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
271c0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
271d0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
271e0 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
271f0 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
27200 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
27210 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
27220 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
27230 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
27240 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
27250 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
27260 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
27270 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
27280 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
27290 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
272a0 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
272b0 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
272c0 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
272d0 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
272e0 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
272f0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
27300 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
27310 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
27320 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
27330 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
27340 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
27350 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
27360 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
27370 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
27380 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
27390 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
273a0 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
273b0 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
273c0 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
273d0 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
273e0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
273f0 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
27400 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
27410 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
27420 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
27430 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
27440 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
27450 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e  * </li>.** </ol>
27460 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
27470 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
27480 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
27490 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
274a0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
274b0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
274c0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
274d0 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
274e0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
274f0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
27500 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
27510 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
27520 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
27530 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
27540 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
27550 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
27560 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
27570 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
27580 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
27590 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
275a0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
275b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
275c0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
275d0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
275e0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
275f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
27600 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
27610 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
27620 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
27630 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
27640 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
27650 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
27660 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
27670 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
27680 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
27690 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
276a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
276b0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
276c0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
276d0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
276e0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
276f0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
27700 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
27710 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
27720 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
27730 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
27740 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
27750 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
27760 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
27770 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
27780 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
27790 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
277a0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
277b0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
277c0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
277d0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
277e0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
277f0 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
27800 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
27810 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
27820 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
27830 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
27840 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73  repare16_v2(.  s
27850 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
27860 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
27870 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
27880 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
27890 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
278a0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
278b0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
278c0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
278d0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
278e0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
278f0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
27900 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
27910 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
27920 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
27930 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
27940 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
27950 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
27960 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
27970 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   zSql */.);../*.
27980 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74  ** CAPI3REF: Ret
27990 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e  rieving Statemen
279a0 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  t SQL.**.** ^Thi
279b0 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
279c0 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
279d0 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
279e0 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
279f0 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
27a00 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
27a10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27a20 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
27a30 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
27a40 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
27a50 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
27a60 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
27a70 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
27a80 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  2()]..*/.const c
27a90 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
27aa0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
27ab0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
27ac0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
27ad0 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
27ae0 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65  ement Writes The
27af0 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20   Database.**.** 
27b00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
27b10 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e  t_readonly(X) in
27b20 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27b30 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
27b40 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69  if.** and only i
27b50 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
27b60 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b  statement] X mak
27b70 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61  es no direct cha
27b80 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63  nges to.** the c
27b90 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
27ba0 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a  tabase file..**.
27bb0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70  ** Note that [ap
27bc0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
27bd0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
27be0 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20   or.** [virtual 
27bf0 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68  tables] might ch
27c00 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
27c10 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20  e indirectly as 
27c20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20  a side effect.  
27c30 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
27c40 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  e, if an applica
27c50 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66  tion defines a f
27c60 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22  unction "eval()"
27c70 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20   that .** calls 
27c80 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
27c90 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f  , then the follo
27ca0 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  wing SQL stateme
27cb0 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e  nt would.** chan
27cc0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
27cd0 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64  file through sid
27ce0 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a  e-effects:.**.**
27cf0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
27d00 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20  e>.**    SELECT 
27d10 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f  eval('DELETE FRO
27d20 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a  M t1') FROM t2;.
27d30 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
27d40 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74  quote>.**.** But
27d50 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45   because the [SE
27d60 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
27d70 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
27d80 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
27d90 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73  e.** directly, s
27da0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
27db0 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69  only() would sti
27dc0 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29  ll return true.)
27dd0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63  ^.**.** ^Transac
27de0 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61  tion control sta
27df0 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20  tements such as 
27e00 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54  [BEGIN], [COMMIT
27e10 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a  ], [ROLLBACK],.*
27e20 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61  * [SAVEPOINT], a
27e30 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75  nd [RELEASE] cau
27e40 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  se sqlite3_stmt_
27e50 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
27e60 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69  turn true,.** si
27e70 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  nce the statemen
27e80 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f  ts themselves do
27e90 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f   not actually mo
27ea0 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
27eb0 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20  e but.** rather 
27ec0 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65  they control the
27ed0 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20   timing of when 
27ee0 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73  other statements
27ef0 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20   modify the .** 
27f00 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20  database.  ^The 
27f10 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45  [ATTACH] and [DE
27f20 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73  TACH] statements
27f30 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73   also cause.** s
27f40 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
27f50 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
27f60 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69   true since, whi
27f70 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65  le those stateme
27f80 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  nts.** change th
27f90 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
27fa0 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  of a database co
27fb0 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64  nnection, they d
27fc0 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63  o not make .** c
27fd0 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f  hanges to the co
27fe0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
27ff0 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64  abase files on d
28000 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  isk..*/.int sqli
28010 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
28020 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  y(sqlite3_stmt *
28030 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
28040 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
28050 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64  ne If A Prepared
28060 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42   Statement Has B
28070 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20  een Reset.**.** 
28080 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
28090 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66  t_busy(S) interf
280a0 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
280b0 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74   (non-zero) if t
280c0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
280d0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73  statement] S has
280e0 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74   been stepped at
280f0 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e   least once usin
28100 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  g .** [sqlite3_s
28110 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20  tep(S)] but has 
28120 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c  not run to compl
28130 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73  etion and/or has
28140 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65   not .** been re
28150 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  set using [sqlit
28160 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e  e3_reset(S)].  ^
28170 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
28180 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65  _busy(S).** inte
28190 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61  rface returns fa
281a0 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55  lse if S is a NU
281b0 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20  LL pointer.  If 
281c0 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e  S is not a .** N
281d0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  ULL pointer and 
281e0 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72  is not a pointer
281f0 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65   to a valid [pre
28200 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28210 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e  .** object, then
28220 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
28230 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
28240 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
28250 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ble..**.** This 
28260 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
28270 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61   used in combina
28280 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65  tion [sqlite3_ne
28290 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f  xt_stmt()].** to
282a0 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70   locate all prep
282b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20  ared statements 
282c0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
282d0 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63  a database .** c
282e0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61  onnection that a
282f0 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65  re in need of be
28300 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73  ing reset.  This
28310 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a   can be used,.**
28320 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e   for example, in
28330 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74   diagnostic rout
28340 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66  ines to search f
28350 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20  or prepared .** 
28360 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
28370 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72  are holding a tr
28380 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a  ansaction open..
28390 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
283a0 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33  tmt_busy(sqlite3
283b0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
283c0 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
283d0 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
283e0 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  e Object.** KEYW
283f0 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
28400 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
28410 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
28420 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
28430 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
28440 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
28450 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
28460 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
28470 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
28480 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
28490 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
284a0 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
284b0 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
284c0 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
284d0 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65  .  ^Values store
284e0 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
284f0 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
28500 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
28510 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
28520 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
28530 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
28540 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
28550 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
28560 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
28570 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
28580 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
28590 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
285a0 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
285b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
285c0 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
285d0 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
285e0 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
285f0 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
28600 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
28610 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
28620 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
28630 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
28640 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
28650 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
28660 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
28670 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
28680 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
28690 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
286a0 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
286b0 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
286c0 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
286d0 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
286e0 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74  is held.  An int
286f0 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
28700 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
28710 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
28720 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
28730 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
28740 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
28750 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
28760 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
28770 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
28780 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
28790 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
287a0 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
287b0 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
287c0 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
287d0 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
287e0 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
287f0 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
28800 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
28810 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
28820 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
28830 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
28840 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
28850 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
28860 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
28870 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
28880 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
28890 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
288a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
288b0 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
288c0 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
288d0 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
288e0 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
288f0 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
28900 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
28910 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
28920 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
28930 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
28940 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
28950 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
28960 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
28970 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
28980 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
28990 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
289a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
289b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
289c0 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
289d0 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
289e0 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
289f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
28a00 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
28a10 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
28a20 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
28a30 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
28a40 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
28a50 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
28a60 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
28a70 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
28a80 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
28a90 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
28aa0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
28ab0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
28ac0 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
28ad0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
28ae0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
28af0 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
28b00 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
28b10 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
28b20 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
28b30 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
28b40 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
28b50 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
28b60 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
28b70 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
28b80 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
28b90 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
28ba0 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
28bb0 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
28bc0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  t.**.** The cont
28bd0 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
28be0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
28bf0 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
28c00 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
28c10 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
28c20 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20    ^A pointer to 
28c30 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
28c40 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20  xt object.** is 
28c50 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
28c60 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69  ameter to [appli
28c70 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
28c80 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
28c90 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
28ca0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
28cb0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
28cc0 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20  ation will pass 
28cd0 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  this.** pointer 
28ce0 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c  through into cal
28cf0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
28d00 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69  esult_int | sqli
28d10 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a  te3_result()],.*
28d20 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  * [sqlite3_aggre
28d30 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c  gate_context()],
28d40 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
28d50 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
28d60 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
28d70 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74  andle()], [sqlit
28d80 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
28d90 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71  ],.** and/or [sq
28da0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
28db0 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
28dc0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
28dd0 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
28de0 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
28df0 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e  CAPI3REF: Bindin
28e00 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
28e10 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a  ared Statements.
28e20 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f  ** KEYWORDS: {ho
28e30 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68  st parameter} {h
28e40 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20  ost parameters} 
28e50 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  {host parameter 
28e60 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  name}.** KEYWORD
28e70 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  S: {SQL paramete
28e80 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  r} {SQL paramete
28e90 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62  rs} {parameter b
28ea0 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28  inding}.**.** ^(
28eb0 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  In the SQL state
28ec0 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20  ment text input 
28ed0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
28ee0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
28ef0 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
28f00 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
28f10 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61  eplaced by a [pa
28f20 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61  rameter] that ma
28f30 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c  tches one of fol
28f40 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61  lowing.** templa
28f50 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  tes:.**.** <ul>.
28f60 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
28f70 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
28f80 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
28f90 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
28fa0 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
28fb0 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74  * In the templat
28fc0 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65  es above, NNN re
28fd0 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65  presents an inte
28fe0 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
28ff0 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e  and VVV represen
29000 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72  ts an alphanumer
29010 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e  ic identifier.)^
29020 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66    ^The values of
29030 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
29040 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
29050 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
29060 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
29070 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
29080 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
29090 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
290a0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
290b0 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
290c0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
290d0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
290e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
290f0 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61  routines is alwa
29100 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ys.** a pointer 
29110 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
29120 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
29130 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73  urned from.** [s
29140 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
29150 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  2()] or its vari
29160 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ants..**.** ^The
29170 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
29180 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
29190 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
291a0 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
291b0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53   ^The leftmost S
291c0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  QL parameter has
291d0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
291e0 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20   ^When the same 
291f0 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72  named.** SQL par
29200 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
29210 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
29220 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
29230 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
29240 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
29250 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
29260 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
29270 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66  .** ^The index f
29280 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
29290 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
292a0 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
292b0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
292c0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
292d0 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
292e0 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a  d.  ^The index.*
292f0 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
29300 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
29310 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
29320 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d  ^The NNN value m
29330 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
29340 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65   and the [sqlite
29350 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61  3_limit()].** pa
29360 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f  rameter [SQLITE_
29370 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
29380 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20  UMBER] (default 
29390 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a  value: 999)..**.
293a0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  ** ^The third ar
293b0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
293c0 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
293d0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
293e0 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
293f0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
29400 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20  te3_bind_text() 
29410 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
29420 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73  text16().** or s
29430 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
29440 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
29450 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f  nter then the fo
29460 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a  urth parameter.*
29470 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64  * is ignored and
29480 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20   the end result 
29490 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73  is the same as s
294a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
294b0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ()..**.** ^(In t
294c0 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
294d0 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
294e0 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
294f0 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
29500 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
29510 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
29520 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
29530 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
29540 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
29550 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
29560 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
29570 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
29580 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74  ters.)^.** ^If t
29590 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
295a0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
295b0 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
295c0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
295d0 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  6().** is negati
295e0 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e  ve, then the len
295f0 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
29600 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
29610 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
29620 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
29630 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20   terminator..** 
29640 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
29650 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
29660 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
29670 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
29680 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72  .** the behavior
29690 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
296a0 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  * If a non-negat
296b0 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  ive fourth param
296c0 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64  eter is provided
296d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
296e0 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _text().** or sq
296f0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
29700 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  6() or sqlite3_b
29710 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65  ind_text64() the
29720 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65  n.** that parame
29730 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20  ter must be the 
29740 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77  byte offset.** w
29750 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
29760 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63  minator would oc
29770 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65  cur assuming the
29780 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c   string were NUL
29790 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  .** terminated. 
297a0 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
297b0 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20  acters occur at 
297c0 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73  byte offsets les
297d0 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76  s than .** the v
297e0 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72  alue of the four
297f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65  th parameter the
29800 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
29810 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c  string value wil
29820 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62  l.** contain emb
29830 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65  edded NULs.  The
29840 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
29850 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67  ssions involving
29860 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68   strings.** with
29870 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
29880 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
29890 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
298a0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c  gument to the BL
298b0 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69  OB and string bi
298c0 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  nding interfaces
298d0 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63  .** is a destruc
298e0 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
298f0 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
29900 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
29910 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
29920 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
29930 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
29940 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f   is called.** to
29950 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
29960 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65  BLOB or string e
29970 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ven if the call 
29980 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c  to bind API fail
29990 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  s..** ^If the fi
299a0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
299b0 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
299c0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
299d0 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
299e0 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
299f0 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
29a00 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
29a10 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
29a20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
29a30 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
29a40 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
29a50 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
29a60 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
29a70 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
29a80 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
29a90 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
29aa0 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
29ab0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
29ac0 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
29ad0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
29ae0 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
29af0 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61  .** ^The sixth a
29b00 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
29b10 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
29b20 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a   must be one of.
29b30 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ** [SQLITE_UTF8]
29b40 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  , [SQLITE_UTF16]
29b50 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
29b60 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  E], or [SQLITE_U
29b70 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70  TF16LE].** to sp
29b80 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69  ecify the encodi
29b90 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69  ng of the text i
29ba0 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
29bb0 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68  meter.  If.** th
29bc0 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74  e sixth argument
29bd0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
29be0 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74  _text64() is not
29bf0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61   one of the.** a
29c00 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68  llowed values sh
29c10 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66  own above, or if
29c20 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
29c30 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a  ng is different.
29c40 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f  ** from the enco
29c50 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62  ding specified b
29c60 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61  y the sixth para
29c70 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
29c80 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75  behavior.** is u
29c90 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
29ca0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
29cb0 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
29cc0 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
29cd0 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
29ce0 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
29cf0 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41  with zeroes.  ^A
29d00 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
29d10 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
29d20 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
29d30 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
29d40 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
29d50 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
29d60 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
29d70 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
29d80 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
29d90 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
29da0 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
29db0 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
29dc0 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
29dd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
29de0 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
29df0 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
29e00 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65  utines..** ^A ne
29e10 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
29e20 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
29e30 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
29e40 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
29e50 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68  ** ^If any of th
29e60 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
29e70 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
29e80 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
29e90 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f  LL pointer.** fo
29ea0 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
29eb0 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69  statement] or wi
29ec0 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74  th a prepared st
29ed0 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63  atement for whic
29ee0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  h.** [sqlite3_st
29ef0 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  ep()] has been c
29f00 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e  alled more recen
29f10 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65  tly than [sqlite
29f20 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74  3_reset()],.** t
29f30 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c  hen the call wil
29f40 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
29f50 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e  _MISUSE].  If an
29f60 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28  y sqlite3_bind_(
29f70 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20  ).** routine is 
29f80 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72  passed a [prepar
29f90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
29fa0 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  at has been fina
29fb0 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65  lized, the.** re
29fc0 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
29fd0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68  d and probably h
29fe0 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42  armful..**.** ^B
29ff0 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
2a000 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
2a010 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2a020 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e   routine..** ^Un
2a030 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
2a040 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
2a050 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
2a060 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2a070 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74  d_* routines ret
2a080 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
2a090 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
2a0a0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
2a0b0 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65   if anything goe
2a0c0 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51  s wrong..** ^[SQ
2a0d0 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67  LITE_TOOBIG] mig
2a0e0 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69  ht be returned i
2a0f0 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20  f the size of a 
2a100 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a  string or BLOB.*
2a110 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73  * exceeds limits
2a120 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c   imposed by [sql
2a130 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
2a140 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
2a150 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  ]) or.** [SQLITE
2a160 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a  _MAX_LENGTH]..**
2a170 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d   ^[SQLITE_RANGE]
2a180 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2a190 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
2a1a0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
2a1b0 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54   range.  ^[SQLIT
2a1c0 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
2a1d0 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
2a1e0 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65   fails..**.** Se
2a1f0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2a200 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2a210 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
2a220 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2a230 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
2a240 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
2a250 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2a260 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
2a270 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c  e3_bind_blob(sql
2a280 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2a290 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2a2a0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
2a2b0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
2a2c0 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71  3_bind_blob64(sq
2a2d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2a2e0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73  , const void*, s
2a2f0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20  qlite3_uint64,. 
2a300 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a310 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76         void(*)(v
2a320 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
2a330 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28  te3_bind_double(
2a340 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a350 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74  nt, double);.int
2a360 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
2a370 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
2a380 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20   int, int);.int 
2a390 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
2a3a0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2a3b0 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69  , int, sqlite3_i
2a3c0 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74  nt64);.int sqlit
2a3d0 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
2a3e0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
2a3f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2a400 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  nd_text(sqlite3_
2a410 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  stmt*,int,const 
2a420 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a  char*,int,void(*
2a430 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
2a440 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2a450 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2a460 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
2a470 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
2a480 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
2a490 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2a4a0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2a4b0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
2a4c0 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
2a4d0 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
2a4e0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
2a4f0 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69  (*)(void*), unsi
2a500 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69  gned char encodi
2a510 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ng);.int sqlite3
2a520 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
2a530 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2a540 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
2a550 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2a560 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
2a570 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a580 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
2a590 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2a5a0 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
2a5b0 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  meters.**.** ^Th
2a5c0 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
2a5d0 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
2a5e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
2a5f0 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
2a600 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
2a610 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
2a620 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2a630 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
2a640 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
2a650 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
2a660 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
2a670 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
2a680 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
2a690 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
2a6a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2a6b0 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
2a6c0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
2a6d0 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
2a6e0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
2a6f0 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
2a700 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
2a710 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
2a720 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
2a730 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
2a740 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
2a750 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
2a760 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
2a770 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
2a780 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
2a790 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
2a7a0 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
2a7b0 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
2a7c0 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
2a7d0 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
2a7e0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2a7f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2a800 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2a810 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2a820 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2a830 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
2a840 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2a850 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2a860 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
2a870 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2a880 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2a890 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2a8a0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
2a8b0 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
2a8c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2a8d0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2a8e0 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
2a8f0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
2a900 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
2a910 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
2a920 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
2a930 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a940 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
2a950 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
2a960 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
2a970 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
2a980 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
2a990 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
2a9a0 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
2a9b0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
2a9c0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
2a9d0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
2a9e0 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
2a9f0 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
2aa00 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
2aa10 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
2aa20 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
2aa30 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
2aa40 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
2aa50 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
2aa60 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
2aa70 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
2aa80 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
2aa90 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
2aaa0 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
2aab0 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
2aac0 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
2aad0 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
2aae0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2aaf0 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
2ab00 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
2ab10 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
2ab20 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
2ab30 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
2ab40 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
2ab50 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
2ab60 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
2ab70 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
2ab80 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
2ab90 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
2aba0 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
2abb0 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
2abc0 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
2abd0 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
2abe0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2abf0 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
2ac00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2ac10 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2ac20 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2ac30 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2ac40 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2ac50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2ac60 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2ac70 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2ac80 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2ac90 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ndex()]..*/.cons
2aca0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2acb0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2acc0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2acd0 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
2ace0 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
2acf0 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
2ad00 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
2ad10 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
2ad20 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
2ad30 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
2ad40 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
2ad50 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
2ad60 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
2ad70 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
2ad80 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
2ad90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
2ada0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2adb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
2adc0 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
2add0 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
2ade0 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
2adf0 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
2ae00 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
2ae10 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
2ae20 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
2ae30 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
2ae40 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
2ae50 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
2ae60 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
2ae70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2ae80 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
2ae90 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2aea0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2aeb0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2aec0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2aed0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2aee0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2aef0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2af00 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2af10 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2af20 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2af30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2af40 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2af50 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
2af60 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
2af70 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
2af80 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
2af90 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
2afa0 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
2afb0 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
2afc0 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
2afd0 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
2afe0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2aff0 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
2b000 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
2b010 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2b020 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
2b030 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
2b040 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
2b050 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
2b060 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
2b070 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
2b080 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2b090 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
2b0a0 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
2b0b0 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52  ult Set.**.** ^R
2b0c0 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
2b0d0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2b0e0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
2b0f0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
2b100 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b110 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75  ment]. ^This rou
2b120 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
2b130 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
2b140 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
2b150 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
2b160 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
2b170 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
2b180 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
2b190 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  so: [sqlite3_dat
2b1a0 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  a_count()].*/.in
2b1b0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2b1c0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2b1d0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2b1e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2b1f0 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
2b200 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
2b210 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2b220 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
2b230 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
2b240 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
2b250 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
2b260 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
2b270 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
2b280 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
2b290 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
2b2a0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2b2b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
2b2c0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
2b2d0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
2b2e0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2b2f0 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
2b300 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2b310 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2b320 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
2b330 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
2b340 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2b350 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b360 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
2b370 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
2b380 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
2b390 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
2b3a0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
2b3b0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
2b3c0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
2b3d0 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
2b3e0 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
2b3f0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
2b400 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
2b410 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
2b420 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b430 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
2b440 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
2b450 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2b460 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
2b470 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
2b480 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
2b490 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
2b4a0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2b4b0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
2b4c0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
2b4d0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
2b4e0 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
2b4f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2b500 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
2b510 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
2b520 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
2b530 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
2b540 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
2b550 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
2b560 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
2b570 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
2b580 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
2b590 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
2b5a0 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
2b5b0 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
2b5c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2b5d0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2b5e0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
2b5f0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
2b600 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
2b610 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
2b620 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
2b630 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
2b640 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
2b650 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
2b660 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
2b670 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
2b680 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
2b690 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
2b6a0 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
2b6b0 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
2b6c0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
2b6d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2b6e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2b6f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b700 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
2b710 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2b720 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
2b730 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
2b740 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b750 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
2b760 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
2b770 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
2b780 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
2b790 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
2b7a0 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73  mine the databas
2b7b0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a  e, table, and.**
2b7c0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
2b7d0 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e  at is the origin
2b7e0 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72   of a particular
2b7f0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
2b800 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74  n.** [SELECT] st
2b810 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  atement..** ^The
2b820 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
2b830 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
2b840 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
2b850 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
2b860 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72  ither a UTF-8 or
2b870 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
2b880 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f   ^The _database_
2b890 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2b8a0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
2b8b0 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
2b8c0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
2b8d0 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
2b8e0 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
2b8f0 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
2b900 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
2b910 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72   name..** ^The r
2b920 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2b930 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
2b940 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2b950 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
2b960 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
2b970 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2b980 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
2b990 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
2b9a0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
2b9b0 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
2b9c0 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
2b9d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
2b9e0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
2b9f0 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
2ba00 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
2ba10 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
2ba20 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
2ba30 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
2ba40 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
2ba50 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
2ba60 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
2ba70 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
2ba80 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
2ba90 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
2baa0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
2bab0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2bac0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
2bad0 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
2bae0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2baf0 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
2bb00 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
2bb10 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
2bb20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
2bb30 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
2bb40 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
2bb50 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
2bb60 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
2bb70 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
2bb80 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
2bb90 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
2bba0 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
2bbb0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2bbc0 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
2bbd0 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
2bbe0 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
2bbf0 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
2bc00 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
2bc10 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
2bc20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
2bc30 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2bc40 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
2bc50 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
2bc60 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
2bc70 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
2bc80 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
2bc90 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
2bca0 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
2bcb0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
2bcc0 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
2bcd0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
2bce0 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
2bcf0 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
2bd00 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
2bd10 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
2bd20 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
2bd30 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
2bd40 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
2bd50 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
2bd60 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
2bd70 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
2bd80 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
2bd90 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
2bda0 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
2bdb0 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
2bdc0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
2bdd0 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
2bde0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
2bdf0 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
2be00 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
2be10 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
2be20 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
2be30 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
2be40 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
2be50 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
2be60 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
2be70 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
2be80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2be90 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
2bea0 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
2beb0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2bec0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
2bed0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
2bee0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
2bef0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
2bf00 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2bf10 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
2bf20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
2bf30 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
2bf40 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
2bf50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2bf60 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
2bf70 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
2bf80 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
2bf90 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2bfa0 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
2bfb0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2bfc0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2bfd0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2bfe0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2bff0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2c000 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
2c010 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2c020 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
2c030 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2c040 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
2c050 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2c060 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2c070 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
2c080 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2c090 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2c0a0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2c0b0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
2c0c0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2c0d0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2c0e0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2c0f0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
2c100 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2c110 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2c120 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
2c130 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
2c140 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
2c150 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
2c160 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
2c170 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2c180 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
2c190 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
2c1a0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
2c1b0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2c1c0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
2c1d0 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
2c1e0 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
2c1f0 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
2c200 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
2c210 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
2c220 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
2c230 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
2c240 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
2c250 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
2c260 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
2c270 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
2c280 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
2c290 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
2c2a0 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
2c2b0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
2c2c0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
2c2d0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2c2e0 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
2c2f0 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
2c300 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
2c310 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
2c320 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
2c330 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
2c340 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
2c350 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
2c360 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
2c370 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
2c380 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
2c390 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
2c3a0 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
2c3b0 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
2c3c0 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
2c3d0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
2c3e0 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
2c3f0 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
2c400 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2c410 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
2c420 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
2c430 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
2c440 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
2c450 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
2c460 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
2c470 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
2c480 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
2c490 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
2c4a0 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
2c4b0 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
2c4c0 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
2c4d0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
2c4e0 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
2c4f0 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
2c500 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
2c510 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
2c520 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
2c530 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
2c540 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
2c550 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
2c560 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
2c570 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
2c580 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
2c590 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
2c5a0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2c5b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2c5c0 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
2c5d0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2c5e0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2c5f0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
2c600 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2c610 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2c620 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
2c630 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2c640 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
2c650 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c660 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
2c670 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
2c680 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
2c690 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2c6a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c6b0 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
2c6c0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
2c6d0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
2c6e0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2c6f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2c700 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
2c710 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
2c720 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
2c730 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
2c740 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
2c750 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
2c760 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
2c770 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
2c780 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2c790 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
2c7a0 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
2c7b0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
2c7c0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
2c7d0 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
2c7e0 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
2c7f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2c800 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2c810 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
2c820 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
2c830 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2c840 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c850 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2c860 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
2c870 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
2c880 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
2c890 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
2c8a0 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
2c8b0 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
2c8c0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2c8d0 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
2c8e0 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
2c8f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
2c900 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
2c910 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
2c920 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
2c930 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
2c940 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
2c950 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
2c960 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
2c970 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
2c980 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
2c990 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2c9a0 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
2c9b0 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
2c9c0 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
2c9d0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
2c9e0 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2c9f0 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
2ca00 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
2ca10 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2ca20 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
2ca30 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
2ca40 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
2ca50 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
2ca60 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
2ca70 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
2ca80 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
2ca90 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
2caa0 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
2cab0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
2cac0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
2cad0 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
2cae0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
2caf0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2cb00 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
2cb10 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
2cb20 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74  n an.** explicit
2cb30 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
2cb40 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
2cb50 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
2cb60 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
2cb70 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
2cb80 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
2cb90 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2cba0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
2cbb0 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
2cbc0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
2cbd0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
2cbe0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
2cbf0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
2cc00 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
2cc10 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
2cc20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
2cc30 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2cc40 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
2cc50 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
2cc60 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2cc70 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
2cc80 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
2cc90 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
2cca0 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
2ccb0 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
2ccc0 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
2ccd0 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
2cce0 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
2ccf0 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
2cd00 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
2cd10 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
2cd20 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
2cd30 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
2cd40 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
2cd50 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
2cd60 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2cd70 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
2cd80 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
2cd90 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
2cda0 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
2cdb0 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
2cdc0 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
2cdd0 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
2cde0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
2cdf0 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
2ce00 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
2ce10 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
2ce20 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
2ce30 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
2ce40 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
2ce50 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
2ce60 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2ce70 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
2ce80 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
2ce90 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
2cea0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
2ceb0 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
2cec0 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
2ced0 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
2cee0 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
2cef0 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
2cf00 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
2cf10 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
2cf20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2cf30 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
2cf40 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2cf50 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
2cf60 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
2cf70 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
2cf80 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
2cf90 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
2cfa0 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
2cfb0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
2cfc0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
2cfd0 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
2cfe0 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
2cff0 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
2d000 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
2d010 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
2d020 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
2d030 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2d040 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
2d050 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
2d060 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2d070 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
2d080 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
2d090 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
2d0a0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2d0b0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
2d0c0 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
2d0d0 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
2d0e0 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
2d0f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2d100 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
2d110 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
2d120 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
2d130 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
2d140 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
2d150 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
2d160 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
2d170 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
2d180 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  1, a call to.** 
2d190 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2d1a0 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61  ] was required a
2d1b0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
2d1c0 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
2d1d0 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74  thing.** other t
2d1e0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
2d1f0 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
2d200 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
2d210 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
2d220 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
2d230 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72   to reset the pr
2d240 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d250 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
2d260 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75  te3_reset()] wou
2d270 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ld result in an 
2d280 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2d290 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73  return from.** s
2d2a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2d2b0 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f  But after versio
2d2c0 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69  n 3.6.23.1, sqli
2d2d0 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
2d2e0 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
2d2f0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
2d300 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
2d310 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
2d320 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
2d330 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
2d340 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
2d350 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
2d360 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
2d370 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
2d380 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
2d390 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
2d3a0 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
2d3b0 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
2d3c0 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
2d3d0 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
2d3e0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
2d3f0 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
2d400 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
2d410 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
2d420 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
2d430 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
2d440 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
2d450 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
2d460 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2d470 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
2d480 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
2d490 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2d4a0 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
2d4b0 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
2d4c0 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
2d4d0 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
2d4e0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2d4f0 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
2d500 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
2d510 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
2d520 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2d530 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2d540 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
2d550 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
2d560 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
2d570 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
2d580 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
2d590 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
2d5a0 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
2d5b0 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
2d5c0 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
2d5d0 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
2d5e0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
2d5f0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
2d600 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
2d610 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
2d620 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
2d630 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
2d640 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2d650 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2d660 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
2d670 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
2d680 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
2d690 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
2d6a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2d6b0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
2d6c0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
2d6d0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
2d6e0 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
2d6f0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
2d700 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
2d710 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
2d720 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2d730 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2d740 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2d750 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
2d760 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2d770 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
2d780 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
2d790 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20  esult set.**.** 
2d7a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2d7b0 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
2d7c0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2d7d0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2d7e0 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
2d7f0 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
2d800 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
2d810 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d820 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
2d830 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2d840 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
2d850 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
2d860 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
2d870 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
2d880 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2d890 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
2d8a0 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
2d8b0 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
2d8c0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2d8d0 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
2d8e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2d8f0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
2d900 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
2d910 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
2d920 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e  LL pointer..** ^
2d930 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2d940 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
2d950 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74  e returns 0 if t
2d960 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
2d970 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2d980 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
2d990 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  d [SQLITE_DONE].
2d9a0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64    ^The sqlite3_d
2d9b0 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20  ata_count(P).** 
2d9c0 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d  will return non-
2d9d0 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73  zero if previous
2d9e0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2d9f0 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
2da00 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  ned.** [SQLITE_R
2da10 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74  OW], except in t
2da20 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b  he case of the [
2da30 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74  PRAGMA increment
2da40 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68  al_vacuum].** wh
2da50 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65  ere it always re
2da60 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65  turns zero since
2da70 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68   each step of th
2da80 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a  at multi-step.**
2da90 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20   pragma returns 
2daa0 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74  0 columns of dat
2dab0 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  a..**.** See als
2dac0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
2dad0 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  mn_count()].*/.i
2dae0 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
2daf0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2db00 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2db10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
2db20 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
2db30 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2db40 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
2db50 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
2db60 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
2db70 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
2db80 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
2db90 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2dba0 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
2dbb0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
2dbc0 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
2dbd0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
2dbe0 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
2dbf0 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
2dc00 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
2dc10 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
2dc20 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
2dc30 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
2dc40 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
2dc50 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2dc60 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
2dc70 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
2dc80 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
2dc90 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
2dca0 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
2dcb0 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
2dcc0 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
2dcd0 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
2dce0 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
2dcf0 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
2dd00 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
2dd10 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
2dd20 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
2dd30 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
2dd40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
2dd50 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
2dd60 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
2dd70 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2dd80 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
2dd90 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
2dda0 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
2ddb0 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
2ddc0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
2ddd0 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
2dde0 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
2ddf0 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
2de00 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
2de10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2de20 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
2de30 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
2de40 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
2de50 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2de60 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s}.**.** These r
2de70 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65  outines form the
2de80 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e   "result set" in
2de90 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
2dea0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2deb0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2dec0 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
2ded0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
2dee0 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
2def0 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
2df00 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
2df10 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
2df20 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
2df30 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
2df40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2df50 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
2df60 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
2df70 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
2df80 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
2df90 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2dfa0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2dfb0 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
2dfc0 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
2dfd0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2dfe0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
2dff0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
2e000 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
2e010 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
2e020 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
2e030 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
2e040 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2e050 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
2e060 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
2e070 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2e080 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
2e090 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
2e0a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2e0b0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
2e0c0 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
2e0d0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
2e0e0 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
2e0f0 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
2e100 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
2e110 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
2e120 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
2e130 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
2e140 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
2e150 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
2e160 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
2e170 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2e180 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2e190 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2e1a0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2e1b0 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
2e1c0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
2e1d0 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
2e1e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2e1f0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
2e200 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
2e210 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
2e220 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
2e230 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
2e240 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2e250 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
2e260 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
2e270 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
2e280 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
2e290 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
2e2a0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2e2b0 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
2e2c0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2e2d0 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
2e2e0 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2e2f0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2e300 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2e310 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
2e320 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
2e330 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
2e340 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
2e350 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
2e360 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
2e370 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2e380 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2e390 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2e3a0 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
2e3b0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
2e3c0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
2e3d0 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
2e3e0 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
2e3f0 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
2e400 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
2e410 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
2e420 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
2e430 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
2e440 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
2e450 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
2e460 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
2e470 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
2e480 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
2e490 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
2e4a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e4b0 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
2e4c0 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
2e4d0 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
2e4e0 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
2e4f0 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
2e500 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
2e510 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
2e520 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
2e530 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2e540 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2e550 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
2e560 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
2e570 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
2e580 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
2e590 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
2e5a0 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
2e5b0 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
2e5c0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
2e5d0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2e5e0 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
2e5f0 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
2e600 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
2e610 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
2e620 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2e630 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2e640 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
2e650 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
2e660 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2e670 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
2e680 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2e690 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
2e6a0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
2e6b0 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
2e6c0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
2e6d0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2e6e0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2e6f0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
2e700 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
2e710 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2e720 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
2e730 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2e740 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
2e750 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
2e760 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2e770 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
2e780 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2e790 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
2e7a0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2e7b0 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
2e7c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2e7d0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
2e7e0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
2e7f0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
2e800 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  r UTF-16 string 
2e810 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2e820 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2e830 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
2e840 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2e850 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2e860 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
2e870 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2e880 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  lt is a UTF-8 st
2e890 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2e8a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2e8b0 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  6() converts.** 
2e8c0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
2e8d0 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65  F-16 and then re
2e8e0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2e8f0 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
2e900 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2e910 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
2e920 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2e930 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73  umn_bytes16() us
2e940 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
2e950 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
2e960 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
2e970 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72   to a UTF-16 str
2e980 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
2e990 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2e9a0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
2e9b0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2e9c0 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
2e9d0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2e9e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2e9f0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2ea00 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20  .** ^The values 
2ea10 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2ea20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2ea30 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  s()] and .** [sq
2ea40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ea50 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69  es16()] do not i
2ea60 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
2ea70 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74  terminators at t
2ea80 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
2ea90 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
2eaa0 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
2eab0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
2eac0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2ead0 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b  n_bytes()] and [
2eae0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2eaf0 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68  ytes16()] are th
2eb00 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
2eb10 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
2eb20 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
2eb30 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
2eb40 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
2eb50 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2eb60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2eb70 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
2eb80 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
2eb90 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
2eba0 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
2ebb0 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
2ebc0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
2ebd0 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
2ebe0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2ebf0 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
2ec00 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20  ength BLOB is a 
2ec10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2ec20 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  .** ^The object 
2ec30 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2ec40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2ec50 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
2ec60 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2ec70 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2ec80 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
2ec90 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2eca0 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
2ecb0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
2ecc0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2ecd0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
2ece0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2ecf0 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
2ed00 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2ed10 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2ed20 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2ed30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2ed40 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
2ed50 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
2ed60 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
2ed70 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
2ed80 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
2ed90 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
2eda0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2edb0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
2edc0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2edd0 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
2ede0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2edf0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
2ee00 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
2ee10 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
2ee20 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
2ee30 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72  propriate.  ^For
2ee40 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
2ee50 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
2ee60 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
2ee70 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
2ee80 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
2ee90 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
2eea0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
2eeb0 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
2eec0 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
2eed0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
2eee0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
2eef0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
2ef00 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
2ef10 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
2ef20 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
2ef30 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2ef40 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
2ef50 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
2ef60 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
2ef70 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
2ef80 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
2ef90 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
2efa0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2efb0 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
2efc0 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
2efd0 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
2efe0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2eff0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
2f000 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
2f010 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2f020 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2f030 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2f040 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2f050 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2f060 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2f070 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2f080 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2f090 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2f0a0 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
2f0b0 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
2f0c0 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
2f0d0 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
2f0e0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2f0f0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2f100 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2f110 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
2f120 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2f130 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
2f140 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
2f150 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
2f160 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2f170 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
2f180 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2f190 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
2f1a0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2f1b0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2f1c0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
2f1d0 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
2f1e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2f1f0 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
2f200 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
2f210 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c  to BLOB.** <tr><
2f220 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
2f230 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2f240 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
2f250 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
2f260 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
2f270 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
2f280 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
2f290 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2f2a0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2f2b0 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
2f2c0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2f2d0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2f2e0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2f2f0 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
2f300 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2f310 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2f320 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
2f330 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2f340 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
2f350 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
2f360 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
2f370 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
2f380 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
2f390 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54  quote>)^.**.** T
2f3a0 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d  he table above m
2f3b0 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74  akes reference t
2f3c0 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  o standard C lib
2f3d0 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61  rary functions a
2f3e0 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f  toi().** and ato
2f3f0 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65  f().  SQLite doe
2f400 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65  s not really use
2f410 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2f420 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a  .  It has its.**
2f430 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20   own equivalent 
2f440 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65  internal routine
2f450 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61  s.  The atoi() a
2f460 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20  nd atof() names 
2f470 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74  are.** used in t
2f480 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65  he table for bre
2f490 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65  vity and because
2f4a0 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69   they are famili
2f4b0 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20  ar to most.** C 
2f4c0 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a  programmers..**.
2f4d0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
2f4e0 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
2f4f0 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
2f500 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
2f510 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
2f520 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f530 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
2f540 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
2f550 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
2f560 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2f570 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
2f580 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
2f590 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
2f5a0 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
2f5b0 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
2f5c0 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
2f5d0 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
2f5e0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
2f5f0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2f600 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
2f610 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f620 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
2f630 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f640 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
2f650 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
2f660 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
2f670 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
2f680 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
2f690 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
2f6a0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2f6b0 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
2f6c0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
2f6d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2f6e0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2f6f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2f700 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
2f710 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
2f720 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
2f730 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
2f740 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
2f750 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2f760 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
2f770 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2f780 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
2f790 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2f7a0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
2f7b0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
2f7c0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
2f7d0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
2f7e0 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
2f7f0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  </ul>.**.** ^Con
2f800 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
2f810 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
2f820 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
2f830 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
2f840 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
2f850 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
2f860 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
2f870 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
2f880 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
2f890 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
2f8a0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72   prior pointer r
2f8b0 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68  eferences will h
2f8c0 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
2f8d0 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
2f8e0 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
2f8f0 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
2f900 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
2f910 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
2f920 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
2f930 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
2f940 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
2f950 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
2f960 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
2f970 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65  ..**.** The safe
2f980 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74  st and easiest t
2f990 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63  o remember polic
2f9a0 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
2f9b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
2f9c0 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
2f9d0 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
2f9e0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  *.** <ul>.**  <l
2f9f0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2fa00 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
2fa10 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2fa20 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
2fa30 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2fa40 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2fa50 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
2fa60 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2fa70 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
2fa80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2fa90 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
2faa0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2fab0 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
2fac0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
2fad0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
2fae0 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
2faf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2fb00 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  xt(),.** sqlite3
2fb10 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
2fb20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2fb30 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
2fb40 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
2fb50 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  sult.** into the
2fb60 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c   desired format,
2fb70 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
2fb80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2fb90 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  s() or.** sqlite
2fba0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2fbb0 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  () to find the s
2fbc0 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
2fbd0 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
2fbe0 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  alls.** to sqlit
2fbf0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2fc00 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2fc10 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
2fc20 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
2fc30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2fc40 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20  6(), and do not 
2fc50 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
2fc60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2fc70 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c  16().** with cal
2fc80 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2fc90 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
2fca0 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72  .** ^The pointer
2fcb0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
2fcc0 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
2fcd0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
2fce0 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
2fcf0 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
2fd00 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
2fd10 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2fd20 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
2fd30 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2fd40 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
2fd50 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61   ^The memory spa
2fd60 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
2fd70 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
2fd80 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
2fd90 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
2fda0 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73   <b>not</b> pass
2fdb0 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
2fdc0 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
2fdd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2fde0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
2fdf0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
2fe00 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
2fe10 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
2fe20 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d  **.** ^(If a mem
2fe30 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
2fe40 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
2fe50 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
2fe60 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
2fe70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
2fe80 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
2fe90 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
2fea0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
2feb0 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
2fec0 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
2fed0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
2fee0 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
2fef0 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
2ff00 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
2ff10 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
2ff20 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
2ff30 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
2ff40 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e  NOMEM].)^.*/.con
2ff50 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2ff60 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
2ff70 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2ff80 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2ff90 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2ffa0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ffb0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2ffc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ffd0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
2ffe0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
2fff0 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
30000 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
30010 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
30020 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
30030 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
30040 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
30050 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
30060 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
30070 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
30080 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
30090 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
300a0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
300b0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
300c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
300d0 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
300e0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
300f0 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
30100 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
30110 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
30120 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
30130 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
30140 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ol);.sqlite3_val
30150 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
30160 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
30170 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
30180 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30190 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
301a0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
301b0 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54   Object.**.** ^T
301c0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
301d0 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
301e0 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
301f0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
30200 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
30210 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
30220 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
30230 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
30240 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
30250 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
30260 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
30270 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
30280 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
30290 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
302a0 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
302b0 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
302c0 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
302d0 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
302e0 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
302f0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
30300 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
30310 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
30320 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
30330 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
30340 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
30350 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
30360 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
30370 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
30380 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
30390 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
303a0 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
303b0 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
303c0 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
303d0 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
303e0 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
303f0 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
30400 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
30410 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
30420 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
30430 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
30440 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
30450 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
30460 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
30470 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
30480 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
30490 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
304a0 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
304b0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
304c0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
304d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
304e0 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
304f0 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
30500 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
30510 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
30520 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
30530 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
30540 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
30550 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
30560 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
30570 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
30580 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
30590 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
305a0 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
305b0 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
305c0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
305d0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
305e0 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
305f0 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
30600 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
30610 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
30620 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
30630 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
30640 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
30650 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
30660 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
30670 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
30680 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
30690 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
306a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
306b0 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69  3_reset() functi
306c0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
306d0 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65  reset a [prepare
306e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
306f0 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69  object back to i
30700 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
30710 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65  , ready to be re
30720 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41  -executed..** ^A
30730 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
30740 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20   variables that 
30750 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64  had values bound
30760 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a   to them using.*
30770 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
30780 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
30790 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d  e3_bind_*() API]
307a0 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61   retain their va
307b0 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71  lues..** Use [sq
307c0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
307d0 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74  ings()] to reset
307e0 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a   the bindings..*
307f0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
30800 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
30810 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68  erface resets th
30820 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
30830 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b  ement] S.** back
30840 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   to the beginnin
30850 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d  g of its program
30860 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
30870 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
30880 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
30890 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
308a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
308b0 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
308c0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
308d0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a   [SQLITE_DONE],.
308e0 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65  ** or if [sqlite
308f0 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e  3_step(S)] has n
30900 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e  ever before been
30910 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a   called on S,.**
30920 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
30930 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
30940 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
30950 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
30960 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
30970 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
30980 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
30990 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
309a0 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
309b0 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
309c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
309d0 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  )] returns an ap
309e0 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
309f0 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
30a00 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
30a10 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
30a20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
30a30 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66  the values.** of
30a40 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69   any [sqlite3_bi
30a50 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73  nd_blob|bindings
30a60 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] on the [prepar
30a70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
30a80 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
30a90 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
30aa0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
30ab0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
30ac0 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
30ad0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  SQL Functions.**
30ae0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
30af0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
30b00 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f  utines}.** KEYWO
30b10 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
30b20 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
30b30 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f  nction}.** KEYWO
30b40 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
30b50 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
30b60 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e  nctions}.**.** ^
30b70 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
30b80 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
30b90 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
30ba0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
30bb0 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
30bc0 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
30bd0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
30be0 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
30bf0 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
30c00 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
30c10 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
30c20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
30c30 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
30c40 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  s between.** the
30c50 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
30c60 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
30c70 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a  g expected for.*
30c80 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * the second par
30c90 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65  ameter (the name
30ca0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
30cb0 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a   being created).
30cc0 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65  ** and the prese
30cd0 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f  nce or absence o
30ce0 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63  f a destructor c
30cf0 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74  allback for.** t
30d00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
30d10 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ata pointer..**.
30d20 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
30d30 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
30d40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30d50 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
30d60 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
30d70 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
30d80 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
30d90 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
30da0 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
30db0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
30dc0 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
30dd0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
30de0 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
30df0 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
30e00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30e10 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
30e20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
30e30 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
30e40 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
30e50 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
30e60 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
30e70 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  redefined.  ^The
30e80 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
30e90 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
30ea0 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61  o 255 bytes in a
30eb0 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73   UTF-8.** repres
30ec0 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73  entation, exclus
30ed0 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d  ive of the zero-
30ee0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f  terminator.  ^No
30ef0 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
30f00 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  .** length limit
30f10 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74   is in UTF-8 byt
30f20 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65  es, not characte
30f30 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79  rs nor UTF-16 by
30f40 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61  tes.  .** ^Any a
30f50 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
30f60 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
30f70 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
30f80 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
30f90 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
30fa0 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
30fb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
30fc0 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
30fd0 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
30fe0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
30ff0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
31000 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
31010 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
31020 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
31030 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
31040 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
31050 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
31060 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
31070 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
31080 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
31090 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
310a0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
310b0 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
310c0 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
310d0 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
310e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
310f0 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
31100 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
31110 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
31120 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
31130 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
31140 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
31150 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
31160 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
31170 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
31180 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
31190 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
311a0 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
311b0 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70  ameters.  The ap
311c0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
311d0 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65   set this parame
311e0 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ter to.** [SQLIT
311f0 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68  E_UTF16LE] if th
31200 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  e function imple
31210 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
31220 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  s .** [sqlite3_v
31230 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d  alue_text16le()]
31240 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72   on an input, or
31250 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
31260 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  ] if the.** impl
31270 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b  ementation invok
31280 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  es [sqlite3_valu
31290 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e  e_text16be()] on
312a0 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a   an input, or.**
312b0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20   [SQLITE_UTF16] 
312c0 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  if [sqlite3_valu
312d0 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75  e_text16()] is u
312e0 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  sed, or [SQLITE_
312f0 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69  UTF8].** otherwi
31300 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53  se.  ^The same S
31310 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  QL function may 
31320 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75  be registered mu
31330 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69  ltiple times usi
31340 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20  ng.** different 
31350 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
31360 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64  ncodings, with d
31370 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65  ifferent impleme
31380 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20  ntations for.** 
31390 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  each encoding..*
313a0 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  * ^When multiple
313b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
313c0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
313d0 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
313e0 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
313f0 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
31400 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
31410 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
31420 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
31430 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  on..**.** ^The f
31440 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
31450 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62  may optionally b
31460 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c  e ORed with [SQL
31470 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
31480 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  C].** to signal 
31490 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f  that the functio
314a0 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65  n will always re
314b0 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65  turn the same re
314c0 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68  sult given.** th
314d0 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69  e same inputs wi
314e0 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51  thin a single SQ
314f0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f  L statement.  Mo
31500 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  st SQL functions
31510 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e   are.** determin
31520 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c  istic.  The buil
31530 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20  t-in [random()] 
31540 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
31550 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a  an example of a.
31560 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ** function that
31570 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e   is not determin
31580 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69  istic.  The SQLi
31590 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  te query planner
315a0 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70   is able to.** p
315b0 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61  erform additiona
315c0 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20  l optimizations 
315d0 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  on deterministic
315e0 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75   functions, so u
315f0 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51  se.** of the [SQ
31600 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
31610 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f  IC] flag is reco
31620 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f  mmended where po
31630 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ssible..**.** ^(
31640 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
31650 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
31660 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
31670 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
31680 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
31690 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
316a0 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
316b0 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
316c0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
316d0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  )^.**.** ^The si
316e0 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64  xth, seventh and
316f0 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65   eighth paramete
31700 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
31710 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
31720 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
31730 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
31740 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
31750 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
31760 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
31770 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20  gate. ^A scalar 
31780 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
31790 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
317a0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
317b0 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
317c0 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e   only; NULL poin
317d0 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73  ters must be pas
317e0 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
317f0 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
31800 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61  arameters. ^An a
31810 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
31820 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
31830 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
31840 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
31850 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
31860 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65   pointer must be
31870 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
31880 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e  c. ^To delete an
31890 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c   existing.** SQL
318a0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
318b0 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
318c0 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61  L pointers for a
318d0 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
318e0 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  n.** callbacks..
318f0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e  **.** ^(If the n
31900 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  inth parameter t
31910 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
31920 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69  _function_v2() i
31930 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74  s not NULL,.** t
31940 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75  hen it is destru
31950 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  ctor for the app
31960 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
31970 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64  inter. .** The d
31980 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76  estructor is inv
31990 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75  oked when the fu
319a0 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
319b0 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69  d, either by bei
319c0 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64  ng.** overloaded
319d0 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74   or when the dat
319e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
319f0 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54   closes.)^.** ^T
31a00 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
31a10 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66   also invoked if
31a20 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
31a30 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
31a40 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69  unction_v2() fai
31a50 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  ls..** ^When the
31a60 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
31a70 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74  back of the tent
31a80 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  h parameter is i
31a90 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73  nvoked, it.** is
31aa0 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65   passed a single
31ab0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
31ac0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
31ad0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
31ae0 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68  a .** pointer wh
31af0 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74  ich was the fift
31b00 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
31b10 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31b20 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  nction_v2()..**.
31b30 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74  ** ^It is permit
31b40 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
31b50 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
31b60 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
31b70 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
31b80 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
31b90 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
31ba0 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
31bb0 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
31bc0 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
31bd0 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
31be0 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e  xt encodings.  ^
31bf0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
31c00 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
31c10 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20  ation that most 
31c20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
31c30 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
31c40 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
31c50 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e  tion is used.  ^
31c60 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  A function imple
31c70 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
31c80 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a   non-negative.**
31c90 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20   nArg parameter 
31ca0 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63  is a better matc
31cb0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
31cc0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
31cd0 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74   with.** a negat
31ce0 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75  ive nArg.  ^A fu
31cf0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
31d00 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
31d10 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
31d20 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
31d30 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
31d40 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
31d50 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
31d60 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
31d70 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
31d80 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e   .** ^A function
31d90 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
31da0 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
31db0 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
31dc0 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
31dd0 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
31de0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
31df0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
31e00 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
31e10 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
31e20 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
31e30 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66  *.** ^Built-in f
31e40 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
31e50 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65  overloaded by ne
31e60 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  w application-de
31e70 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e  fined functions.
31e80 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69  .**.** ^An appli
31e90 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
31ea0 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
31eb0 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
31ec0 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
31ed0 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
31ee0 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
31ef0 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
31f00 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
31f10 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61  nection nor fina
31f20 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
31f30 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
31f40 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
31f50 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
31f60 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74   running..*/.int
31f70 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
31f80 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
31f90 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
31fa0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
31fb0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
31fc0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
31fd0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
31fe0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
31ff0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32000 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
32010 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
32020 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
32030 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
32040 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
32050 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
32060 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
32070 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
32080 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
32090 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
320a0 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
320b0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
320c0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
320d0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
320e0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
320f0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
32100 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
32110 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
32120 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
32130 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32140 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
32150 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
32160 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
32170 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
32180 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32190 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73  function_v2(.  s
321a0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
321b0 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
321c0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
321d0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
321e0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
321f0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
32200 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
32210 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
32220 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
32230 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
32240 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
32250 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
32260 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
32270 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
32280 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  t*),.  void(*xDe
32290 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
322a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
322b0 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
322c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
322d0 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
322e0 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
322f0 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
32300 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
32310 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
32320 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
32330 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
32340 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 20  TF8           1 
32350 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35     /* IMP: R-375
32360 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66  14-35566 */.#def
32370 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
32380 4c 45 20 20 20 20 20 20 20 20 32 20 20 20 20 2f  LE        2    /
32390 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33  * IMP: R-03371-3
323a0 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20  7637 */.#define 
323b0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
323c0 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d        3    /* IM
323d0 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34  P: R-51971-34154
323e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
323f0 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
32400 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
32410 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
32420 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
32430 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
32440 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61   5    /* Depreca
32450 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ted */.#define S
32460 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
32470 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c  NED  8    /* sql
32480 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
32490 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  ation only */../
324a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
324b0 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a  unction Flags.**
324c0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
324d0 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20  nts may be ORed 
324e0 74 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68  together with th
324f0 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  e .** [SQLITE_UT
32500 46 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74  F8 | preferred t
32510 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73  ext encoding] as
32520 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
32530 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ment.** to [sqli
32540 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32550 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
32560 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32570 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
32580 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
32590 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  ction_v2()]..*/.
325a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
325b0 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20  ETERMINISTIC    
325c0 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  0x800../*.** CAP
325d0 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
325e0 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
325f0 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
32600 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
32610 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
32620 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
32630 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
32640 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
32650 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
32660 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
32670 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
32680 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
32690 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
326a0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
326b0 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
326c0 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
326d0 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
326e0 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
326f0 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
32700 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
32710 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
32720 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
32730 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  ou what they do.
32740 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
32750 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
32760 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ED.SQLITE_DEPREC
32770 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
32780 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
32790 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
327a0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
327b0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
327c0 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
327d0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
327e0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
327f0 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
32800 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
32810 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
32820 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
32830 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
32840 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
32850 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
32860 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
32870 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
32880 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
32890 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
328a0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
328b0 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
328c0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
328d0 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20  e3_int64,int),. 
328e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
328f0 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74       void*,sqlit
32900 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69  e3_int64);.#endi
32910 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
32920 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
32930 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65   Function Parame
32940 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a  ter Values.**.**
32950 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20   The C-language 
32960 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
32970 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  f SQL functions 
32980 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75  and aggregates u
32990 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20  ses.** this set 
329a0 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  of interface rou
329b0 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20  tines to access 
329c0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61  the parameter va
329d0 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66  lues on.** the f
329e0 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
329f0 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gate..**.** The 
32a00 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61  xFunc (for scala
32a10 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20  r functions) or 
32a20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65  xStep (for aggre
32a30 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72  gates) parameter
32a40 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
32a50 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32a60 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
32a70 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32a80 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20  16()].** define 
32a90 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69  callbacks that i
32aa0 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
32ab0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
32ac0 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68  ggregates..** Th
32ad0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
32ae0 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63  to these callbac
32af0 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ks is an array o
32b00 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a  f pointers to.**
32b10 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
32b20 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
32b30 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e  ts.  There is on
32b40 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
32b50 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20  ] object for.** 
32b60 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74  each parameter t
32b70 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
32b80 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  on.  These routi
32b90 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a  nes are used to.
32ba0 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65  ** extract value
32bb0 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  s from the [sqli
32bc0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
32bd0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ts..**.** These 
32be0 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e  routines work on
32bf0 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74  ly with [protect
32c00 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32c10 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e  ] objects..** An
32c20 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  y attempt to use
32c30 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
32c40 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  on an [unprotect
32c50 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32c60 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75  ].** object resu
32c70 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
32c80 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
32c90 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
32ca0 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20   work just like 
32cb0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
32cc0 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  g [column access
32cd0 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65   functions].** e
32ce0 78 63 65 70 74 20 74 68 61 74 20 74 68 65 73 65  xcept that these
32cf0 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
32d00 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74   single [protect
32d10 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32d20 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e  ] object.** poin
32d30 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  ter instead of a
32d40 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
32d50 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20   pointer and an 
32d60 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e  integer column n
32d70 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  umber..**.** ^Th
32d80 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
32d90 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
32da0 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
32db0 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69  F-16 string.** i
32dc0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
32dd0 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68  e-order of the h
32de0 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54  ost machine.  ^T
32df0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  he.** sqlite3_va
32e00 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61  lue_text16be() a
32e10 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nd sqlite3_value
32e20 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65  _text16le() inte
32e30 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63  rfaces.** extrac
32e40 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73  t UTF-16 strings
32e50 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61   as big-endian a
32e60 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  nd little-endian
32e70 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
32e80 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
32e90 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
32ea0 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
32eb0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
32ec0 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
32ed0 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
32ee0 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
32ef0 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
32f00 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
32f10 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
32f20 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
32f30 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
32f40 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
32f50 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
32f60 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
32f70 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
32f80 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
32f90 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76   words, if the v
32fa0 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67  alue is a string
32fb0 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
32fc0 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
32fd0 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  en the conversio
32fe0 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20  n is performed. 
32ff0 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
33000 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
33010 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
33020 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
33030 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
33040 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
33050 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65  .)^.**.** Please
33060 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20   pay particular 
33070 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65  attention to the
33080 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70   fact that the p
33090 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a  ointer returned.
330a0 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
330b0 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20  _value_blob()], 
330c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
330d0 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  ext()], or.** [s
330e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
330f0 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e  t16()] can be in
33100 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73  validated by a s
33110 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
33120 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  o.** [sqlite3_va
33130 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73  lue_bytes()], [s
33140 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
33150 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  es16()], [sqlite
33160 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
33170 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
33180 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e  value_text16()].
33190 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
331a0 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
331b0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
331c0 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20  me thread as.** 
331d0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
331e0 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74   that supplied t
331f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
33200 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  e*] parameters..
33210 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
33220 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
33230 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  b(sqlite3_value*
33240 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
33250 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
33260 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
33270 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
33280 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
33290 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71  lue*);.double sq
332a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
332b0 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
332c0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
332d0 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
332e0 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74  3_value*);.sqlit
332f0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
33300 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
33310 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
33320 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
33330 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
33340 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
33350 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
33360 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
33370 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
33380 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
33390 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
333a0 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
333b0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
333c0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
333d0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
333e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
333f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
33400 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
33410 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
33420 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
33430 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ic_type(sqlite3_
33440 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
33450 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
33460 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
33470 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  ion Context.**.*
33480 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * Implementation
33490 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53  s of aggregate S
334a0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  QL functions use
334b0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
334c0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
334d0 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ory for storing 
334e0 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a  their state..**.
334f0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
33500 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61  me the sqlite3_a
33510 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
33520 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73  (C,N) routine is
33530 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20   called .** for 
33540 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67  a particular agg
33550 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c  regate function,
33560 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63   SQLite.** alloc
33570 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79  ates N of memory
33580 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61  , zeroes out tha
33590 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
335a0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a  turns a pointer.
335b0 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65  ** to the new me
335c0 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64  mory. ^On second
335d0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
335e0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
335f0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
33600 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20  ntext() for the 
33610 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
33620 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
33630 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75  ,.** the same bu
33640 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  ffer is returned
33650 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65  .  Sqlite3_aggre
33660 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69  gate_context() i
33670 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61  s normally.** ca
33680 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61  lled once for ea
33690 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ch invocation of
336a0 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62   the xStep callb
336b0 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65  ack and then one
336c0 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68  .** last time wh
336d0 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  en the xFinal ca
336e0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
336f0 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f  d.  ^(When no ro
33700 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61  ws match.** an a
33710 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20  ggregate query, 
33720 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c  the xStep() call
33730 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72  back of the aggr
33740 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  egate function.*
33750 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
33760 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64   is never called
33770 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73   and xFinal() is
33780 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20   called exactly 
33790 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73  once..** In thos
337a0 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33  e cases, sqlite3
337b0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
337c0 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61  xt() might be ca
337d0 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20  lled for the.** 
337e0 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20  first time from 
337f0 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e  within xFinal().
33800 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
33810 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
33820 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
33830 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e  tine returns a N
33840 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20  ULL pointer .** 
33850 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65  when first calle
33860 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74  d if N is less t
33870 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
33880 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d  zero or if a mem
33890 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20  ory.** allocate 
338a0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
338b0 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74  .** ^(The amount
338c0 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61   of space alloca
338d0 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61  ted by sqlite3_a
338e0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
338f0 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65  (C,N) is.** dete
33900 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20  rmined by the N 
33910 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72  parameter on fir
33920 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  st successful ca
33930 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68  ll.  Changing th
33940 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20  e.** value of N 
33950 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
33960 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ll to sqlite3_ag
33970 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
33980 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  ) within.** the 
33990 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
339a0 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
339b0 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65   will not resize
339c0 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
339d0 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69  llocation.)^  Wi
339e0 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  thin the xFinal 
339f0 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20  callback, it is 
33a00 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74  customary to set
33a10 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73  .** N=0 in calls
33a20 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
33a30 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
33a40 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a  N) so that no .*
33a50 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f  * pointless memo
33a60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f  ry allocations o
33a70 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ccur..**.** ^SQL
33a80 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
33a90 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f  y frees the memo
33aa0 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ry allocated by 
33ab0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
33ac0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
33ad0 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61  when the aggrega
33ae0 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  te query conclud
33af0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
33b00 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  rst parameter mu
33b10 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20  st be a copy of 
33b20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
33b30 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75  context | SQL fu
33b40 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20  nction context] 
33b50 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73  that is the firs
33b60 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  t parameter.** t
33b70 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78  o the xStep or x
33b80 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72  Final callback r
33b90 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c  outine that impl
33ba0 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65  ements the aggre
33bb0 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gate.** function
33bc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
33bd0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
33be0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
33bf0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
33c00 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61  h.** the aggrega
33c10 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
33c20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
33c30 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67  oid *sqlite3_agg
33c40 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
33c50 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33c60 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
33c70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
33c80 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
33c90 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
33ca0 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
33cb0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
33cc0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
33cd0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
33ce0 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
33cf0 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
33d00 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
33d10 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
33d20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
33d30 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
33d40 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
33d50 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
33d60 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
33d70 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
33d80 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
33d90 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
33da0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
33db0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
33dc0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
33dd0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
33de0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
33df0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
33e00 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
33e10 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
33e20 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  d *sqlite3_user_
33e30 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
33e40 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
33e50 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
33e60 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72  e Connection For
33e70 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
33e80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
33e90 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
33ea0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
33eb0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
33ec0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
33ed0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
33ee0 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31  nnection] (the 1
33ef0 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
33f00 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
33f10 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
33f20 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
33f30 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33f40 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
33f50 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
33f60 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
33f70 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
33f80 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
33f90 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
33fa0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
33fb0 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
33fc0 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
33fd0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
33fe0 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
33ff0 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ata.**.** These 
34000 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
34010 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67   used by (non-ag
34020 67 72 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e  gregate) SQL fun
34030 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73  ctions to.** ass
34040 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20  ociate metadata 
34050 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
34060 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
34070 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
34080 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
34090 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
340a0 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
340b0 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
340c0 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
340d0 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
340e0 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
340f0 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74  sociated metadat
34100 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
34110 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a  ed.  An example.
34120 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69 73  ** of where this
34130 20 6d 69 67 68 74 20 62 65 20 75 73 65 66 75 6c   might be useful
34140 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72   is in a regular
34150 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
34160 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  hing.** function
34170 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
34180 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
34190 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
341a0 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61   can be stored a
341b0 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73  s.** metadata as
341c0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
341d0 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  e pattern string
341e0 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c  .  .** Then as l
341f0 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74 74 65  ong as the patte
34200 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e  rn string remain
34210 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74  s the same,.** t
34220 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
34230 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
34240 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
34250 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
34260 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
34270 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ame function..**
34280 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34290 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
342a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
342b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
342c0 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  e metadata.** as
342d0 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20  sociated by the 
342e0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
342f0 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77  ata() function w
34300 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
34310 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f  ment.** value to
34320 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34330 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
34340 6e 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  n. ^If there is 
34350 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  no metadata.** a
34360 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
34370 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  he function argu
34380 6d 65 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74  ment, this sqlit
34390 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
343a0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65   interface.** re
343b0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
343c0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
343d0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
343e0 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e  data(C,N,P,X) in
343f0 74 65 72 66 61 63 65 20 73 61 76 65 73 20 50 20  terface saves P 
34400 61 73 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  as metadata for 
34410 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75  the N-th.** argu
34420 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c  ment of the appl
34430 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34440 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73  function.  ^Subs
34450 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
34460 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  to sqlite3_get_a
34470 75 78 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75  uxdata(C,N) retu
34480 72 6e 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f  rn P from the mo
34490 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c  st recent.** sql
344a0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
344b0 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69  (C,N,P,X) call i
344c0 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  f the metadata i
344d0 73 20 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72  s still valid or
344e0 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20  .** NULL if the 
344f0 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
34500 6e 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20  n discarded..** 
34510 5e 41 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c  ^After each call
34520 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
34530 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
34540 20 77 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20   where X is not 
34550 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  NULL,.** SQLite 
34560 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
34570 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
34580 69 6f 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d  ion X with param
34590 65 74 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a  eter P exactly.*
345a0 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65  * once, when the
345b0 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 69 73   metadata is dis
345c0 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74  carded..** SQLit
345d0 65 20 69 73 20 66 72 65 65 20 74 6f 20 64 69 73  e is free to dis
345e0 63 61 72 64 20 74 68 65 20 6d 65 74 61 64 61 74  card the metadat
345f0 61 20 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69  a at any time, i
34600 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a  ncluding: <ul>.*
34610 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20  * <li> when the 
34620 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75  corresponding fu
34630 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
34640 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20   changes, or.** 
34650 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74  <li> when [sqlit
34660 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
34670 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
34680 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f  ()] is called fo
34690 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51  r the.**      SQ
346a0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a  L statement, or.
346b0 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c  ** <li> when sql
346c0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
346d0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67  () is invoked ag
346e0 61 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ain on the same 
346f0 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a  parameter, or.**
34700 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65   <li> during the
34710 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65   original sqlite
34720 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
34730 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f  call when a memo
34740 72 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f  ry .**      allo
34750 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
34760 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  urs. </ul>)^.**.
34770 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74  ** Note the last
34780 20 62 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69   bullet in parti
34790 63 75 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74  cular.  The dest
347a0 72 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20  ructor X in .** 
347b0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
347c0 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67  ata(C,N,P,X) mig
347d0 68 74 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d  ht be called imm
347e0 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
347f0 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
34800 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
34810 74 65 72 66 61 63 65 20 65 76 65 6e 20 72 65 74  terface even ret
34820 75 72 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c  urns.  Hence sql
34830 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
34840 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  ().** should be 
34850 63 61 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20  called near the 
34860 65 6e 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74  end of the funct
34870 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
34880 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75  on and the.** fu
34890 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
348a0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
348b0 20 6d 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66   make any use of
348c0 20 50 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69   P after.** sqli
348d0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
348e0 29 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ) has been calle
348f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72  d..**.** ^(In pr
34900 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61  actice, metadata
34910 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65   is preserved be
34920 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63  tween function c
34930 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63  alls for.** func
34940 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tion parameters 
34950 74 68 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65  that are compile
34960 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c  -time constants,
34970 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72   including liter
34980 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64  al.** values and
34990 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e   [parameters] an
349a0 64 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f  d expressions co
349b0 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20  mposed from the 
349c0 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  same.)^.**.** Th
349d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
349e0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
349f0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
34a00 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
34a10 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
34a20 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
34a30 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
34a40 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
34a50 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
34a60 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65  .void sqlite3_se
34a70 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
34a80 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
34a90 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28  N, void*, void (
34aa0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a  *)(void*));.../*
34ab0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
34ac0 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67  nstants Defining
34ad0 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63   Special Destruc
34ae0 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a  tor Behavior.**.
34af0 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
34b00 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
34b10 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
34b20 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
34b30 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
34b40 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
34b50 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
34b60 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
34b70 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73  )].  ^If the des
34b80 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
34b90 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
34ba0 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
34bb0 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
34bc0 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
34bd0 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
34be0 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
34bf0 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
34c00 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
34c10 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45    ^The.** SQLITE
34c20 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
34c30 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
34c40 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
34c50 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
34c60 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
34c70 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
34c80 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
34c90 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
34ca0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
34cb0 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
34cc0 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
34cd0 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
34ce0 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
34cf0 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
34d00 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
34d10 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70  ompilers..*/.typ
34d20 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
34d30 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
34d40 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
34d50 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
34d60 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
34d70 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
34d80 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
34d90 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
34da0 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
34db0 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
34dc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
34dd0 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
34de0 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
34df0 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  tion.**.** These
34e00 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
34e10 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20  ed by the xFunc 
34e20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
34e30 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c  cks that.** impl
34e40 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69  ement SQL functi
34e50 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
34e60 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c  es.  See.** [sql
34e70 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
34e80 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
34e90 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
34ea0 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72  tion16()].** for
34eb0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
34ec0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
34ed0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77  hese functions w
34ee0 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69  ork very much li
34ef0 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65  ke the [paramete
34f00 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c  r binding] famil
34f10 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  y of.** function
34f20 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76  s used to bind v
34f30 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61  alues to host pa
34f40 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70  rameters in prep
34f50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e  ared statements.
34f60 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65  .** Refer to the
34f70 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
34f80 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
34f90 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
34fa0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
34fb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
34fc0 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65  sult_blob() inte
34fd0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
34fe0 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
34ff0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
35000 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
35010 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f   be the BLOB who
35020 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f  se content is po
35030 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74  inted.** to by t
35040 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
35050 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73  ter and which is
35060 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68   N bytes long wh
35070 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
35080 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
35090 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
350a0 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
350b0 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73  lob() interfaces
350c0 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20   set the result 
350d0 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
350e0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
350f0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42  nction to be a B
35100 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  LOB containing a
35110 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73  ll zero.** bytes
35120 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20   and N bytes in 
35130 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73  size, where N is
35140 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
35150 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
35160 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35170 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
35180 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
35190 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
351a0 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
351b0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
351c0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
351d0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
351e0 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
351f0 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
35200 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
35210 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35220 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
35230 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
35240 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  6() functions.**
35250 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65   cause the imple
35260 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74  mented SQL funct
35270 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ion to throw an 
35280 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53  exception..** ^S
35290 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
352a0 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
352b0 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70   by the.** 2nd p
352c0 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
352d0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
352e0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
352f0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
35300 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66  * as the text of
35310 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
35320 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65  e.  ^SQLite inte
35330 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72  rprets the error
35340 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69  .** message stri
35350 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
35360 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
35370 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65  s UTF-8. ^SQLite
35380 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74  .** interprets t
35390 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  he string from s
353a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
353b0 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31  ror16() as UTF-1
353c0 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62  6 in native.** b
353d0 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20  yte order.  ^If 
353e0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
353f0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
35400 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
35410 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
35420 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
35430 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
35440 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68  Lite takes as th
35450 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
35460 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74  ge all text up t
35470 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
35480 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
35490 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
354a0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
354b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
354c0 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ror() or.** sqli
354d0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
354e0 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  16() is non-nega
354f0 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
35500 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79   takes that many
35510 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63  .** bytes (not c
35520 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20  haracters) from 
35530 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
35540 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d  r as the error m
35550 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20  essage..** ^The 
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 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
35580 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
35590 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
355a0 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63  make a private c
355b0 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72  opy of the error
355c0 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65   message text be
355d0 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74  fore.** they ret
355e0 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  urn.  Hence, the
355f0 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
35600 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65  n can deallocate
35610 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68   or.** modify th
35620 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65  e text after the
35630 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74  y return without
35640 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73   harm..** ^The s
35650 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35660 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
35670 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
35680 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
35690 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
356a0 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
356b0 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
356c0 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66  nction.  ^By def
356d0 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72  ault,.** the err
356e0 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54  or code is SQLIT
356f0 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62  E_ERROR.  ^A sub
35700 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
35710 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35720 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
35730 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35740 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65  r16() resets the
35750 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53   error code to S
35760 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a  QLITE_ERROR..**.
35770 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35780 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
35790 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  big() interface 
357a0 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
357b0 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72   throw an.** err
357c0 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  or indicating th
357d0 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  at a string or B
357e0 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20  LOB is too long 
357f0 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a  to represent..**
35800 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35810 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
35820 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20  mem() interface 
35830 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
35840 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72   throw an.** err
35850 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  or indicating th
35860 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  at a memory allo
35870 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a  cation failed..*
35880 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35890 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69  3_result_int() i
358a0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
358b0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
358c0 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
358d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
358e0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
358f0 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
35900 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
35910 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
35920 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
35930 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
35940 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61  _int64() interfa
35950 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
35960 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
35970 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
35980 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
35990 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74  to be the 64-bit
359a0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
359b0 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
359c0 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
359d0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
359e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
359f0 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
35a00 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
35a10 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
35a20 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35a30 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
35a40 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  e NULL..**.** ^T
35a50 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35a60 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65  t_text(), sqlite
35a70 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
35a80 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  ),.** sqlite3_re
35a90 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c  sult_text16le(),
35aa0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
35ab0 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69  ult_text16be() i
35ac0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74  nterfaces.** set
35ad0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
35ae0 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
35af0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
35b00 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61  ction to be.** a
35b10 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69   text string whi
35b20 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  ch is represente
35b30 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d  d as UTF-8, UTF-
35b40 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
35b50 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  rder,.** UTF-16 
35b60 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f  little endian, o
35b70 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64  r UTF-16 big end
35b80 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
35b90 79 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  y..** ^The sqlit
35ba0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 36 34  e3_result_text64
35bb0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
35bc0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
35bd0 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 61 70 70 6c  ue of an.** appl
35be0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
35bf0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
35c00 20 74 65 78 74 20 73 74 72 69 6e 67 20 69 6e 20   text string in 
35c10 61 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 73  an encoding.** s
35c20 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
35c30 66 69 66 74 68 20 28 61 6e 64 20 6c 61 73 74 29  fifth (and last)
35c40 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63   parameter, whic
35c50 68 20 6d 75 73 74 20 62 65 20 6f 6e 65 0a 2a 2a  h must be one.**
35c60 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   of [SQLITE_UTF8
35c70 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
35c80 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
35c90 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  BE], or [SQLITE_
35ca0 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20 5e 53 51  UTF16LE]..** ^SQ
35cb0 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
35cc0 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
35cd0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
35ce0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
35cf0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
35d00 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35d10 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
35d20 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
35d30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
35d40 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
35d50 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
35d60 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
35d70 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
35d80 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
35d90 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
35da0 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67  ameter.** throug
35db0 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
35dc0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
35dd0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
35de0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
35df0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
35e00 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
35e10 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
35e20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
35e30 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
35e40 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
35e50 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
35e60 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
35e70 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
35e80 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
35e90 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
35ea0 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20  ion result.  If 
35eb0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
35ec0 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  r is non-negativ
35ed0 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75  e, then it.** mu
35ee0 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
35ef0 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73  ffset into the s
35f00 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20  tring where the 
35f10 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
35f20 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69  ould.** appear i
35f30 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65  f the string whe
35f40 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65  re NUL terminate
35f50 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
35f60 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a  haracters occur.
35f70 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  ** in the string
35f80 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65   at a byte offse
35f90 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74  t that is less t
35fa0 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66  han the value of
35fb0 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61   the 3rd.** para
35fc0 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
35fd0 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
35fe0 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d   will contain em
35ff0 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20  bedded NULs and 
36000 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66  the.** result of
36010 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65   expressions ope
36020 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67  rating on string
36030 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  s with embedded 
36040 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
36050 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  d..** ^If the 4t
36060 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
36070 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36080 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
36090 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
360a0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
360b0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
360c0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
360d0 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
360e0 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
360f0 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
36100 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
36110 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
36120 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
36130 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
36140 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
36150 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
36160 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
36170 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f  xt* interfaces o
36180 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
36190 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
361a0 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
361b0 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ant SQLITE_STATI
361c0 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a  C, then SQLite.*
361d0 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  * assumes that t
361e0 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
361f0 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e  result is in con
36200 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20  stant space and 
36210 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79  does not.** copy
36220 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
36230 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f  the parameter no
36240 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
36250 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65  tor on the conte
36260 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61  nt.** when it ha
36270 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
36280 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
36290 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
362a0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
362b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
362c0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
362d0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
362e0 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
362f0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
36300 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
36310 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20  .** then SQLite 
36320 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
36330 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
36340 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66  space obtained f
36350 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  rom.** from [sql
36360 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62  ite3_malloc()] b
36370 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
36380 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36390 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
363a0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
363b0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  ts the result of
363c0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
363d0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
363e0 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70  tion to be a cop
363f0 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74  y the.** [unprot
36400 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
36410 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63  lue] object spec
36420 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64  ified by the 2nd
36430 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68   parameter.  ^Th
36440 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  e.** sqlite3_res
36450 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
36460 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
36470 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
36480 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20  e3_value].** so 
36490 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
364a0 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
364b0 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
364c0 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
364d0 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
364e0 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
364f0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
36500 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
36510 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72   harm..** ^A [pr
36520 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
36530 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61  value] object ma
36540 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64  y always be used
36550 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e   where an.** [un
36560 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
36570 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
36580 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20  is required, so 
36590 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f  either.** kind o
365a0 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
365b0 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20  ] object can be 
365c0 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69  used with this i
365d0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
365e0 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  If these routine
365f0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  s are called fro
36600 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66  m within the dif
36610 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a  ferent thread.**
36620 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f   than the one co
36630 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70  ntaining the app
36640 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36650 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72   function that r
36660 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b  eceived.** the [
36670 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
36680 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65   pointer, the re
36690 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
366a0 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ned..*/.void sql
366b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
366c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
366d0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
366e0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
366f0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
36700 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 36 34  e3_result_blob64
36710 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36720 2a 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 0a 20  *,const void*,. 
36730 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36740 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
36750 33 5f 75 69 6e 74 36 34 2c 76 6f 69 64 28 2a 29  3_uint64,void(*)
36760 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
36770 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
36780 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
36790 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
367a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
367b0 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65  ult_error(sqlite
367c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
367d0 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76  t char*, int);.v
367e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
367f0 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74  lt_error16(sqlit
36800 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
36810 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  st void*, int);.
36820 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36830 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
36840 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36850 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
36860 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
36870 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  mem(sqlite3_cont
36880 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
36890 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
368a0 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f  _code(sqlite3_co
368b0 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
368c0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
368d0 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  t_int(sqlite3_co
368e0 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
368f0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36900 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  t_int64(sqlite3_
36910 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
36920 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73  3_int64);.void s
36930 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
36940 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ll(sqlite3_conte
36950 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
36960 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73  e3_result_text(s
36970 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36980 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
36990 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
369a0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
369b0 5f 72 65 73 75 6c 74 5f 74 65 78 74 36 34 28 73  _result_text64(s
369c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
369d0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c   const char*,sql
369e0 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20  ite3_uint64,.   
369f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36a00 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28          void(*)(
36a10 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64  void*), unsigned
36a20 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b   char encoding);
36a30 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
36a40 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69  sult_text16(sqli
36a50 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
36a60 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
36a70 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
36a80 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
36a90 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71  sult_text16le(sq
36aa0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36ab0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
36ac0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
36ad0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36ae0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73  esult_text16be(s
36af0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36b00 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
36b10 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
36b20 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
36b30 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c  result_value(sql
36b40 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
36b50 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
36b60 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36b70 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ult_zeroblob(sql
36b80 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
36b90 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
36ba0 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e  PI3REF: Define N
36bb0 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71  ew Collating Seq
36bc0 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  uences.**.** ^Th
36bd0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64  ese functions ad
36be0 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f  d, remove, or mo
36bf0 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f  dify a [collatio
36c00 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  n] associated.**
36c10 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
36c20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36c30 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65  specified as the
36c40 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
36c50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
36c60 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
36c70 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  n is a UTF-8 str
36c80 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  ing.** for sqlit
36c90 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36ca0 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ion() and sqlite
36cb0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
36cc0 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61  on_v2().** and a
36cd0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
36ce0 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
36cf0 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
36d00 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36d10 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74  16()..** ^Collat
36d20 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63  ion names that c
36d30 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 63  ompare equal acc
36d40 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74  ording to [sqlit
36d50 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61  e3_strnicmp()] a
36d60 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
36d70 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20   to be the same 
36d80 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  name..**.** ^(Th
36d90 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
36da0 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 74   (eTextRep) must
36db0 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   be one of the c
36dc0 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c  onstants:.** <ul
36dd0 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
36de0 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e  E_UTF8],.** <li>
36df0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
36e00 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
36e10 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
36e20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
36e30 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  16], or.** <li> 
36e40 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
36e50 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  IGNED]..** </ul>
36e60 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74  )^.** ^The eText
36e70 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74  Rep argument det
36e80 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f  ermines the enco
36e90 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20  ding of strings 
36ea0 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65  passed.** to the
36eb0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
36ec0 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43  ion callback, xC
36ed0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65  allback..** ^The
36ee0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20   [SQLITE_UTF16] 
36ef0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  and [SQLITE_UTF1
36f00 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65  6_ALIGNED] value
36f10 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a  s for eTextRep.*
36f20 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20  * force strings 
36f30 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 68  to be UTF16 with
36f40 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
36f50 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  er..** ^The [SQL
36f60 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
36f70 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65  D] value for eTe
36f80 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 72  xtRep forces str
36f90 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a  ings to begin.**
36fa0 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65   on an even byte
36fb0 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20   address..**.** 
36fc0 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75  ^The fourth argu
36fd0 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61  ment, pArg, is a
36fe0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  n application da
36ff0 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  ta pointer that 
37000 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72  is passed.** thr
37010 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
37020 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
37030 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
37040 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  tion callback..*
37050 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
37060 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62  argument, xCallb
37070 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65  ack, is a pointe
37080 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  r to the collati
37090 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ng function..** 
370a0 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74  ^Multiple collat
370b0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61  ing functions ca
370c0 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  n be registered 
370d0 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e  using the same n
370e0 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20  ame but.** with 
370f0 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52  different eTextR
37100 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e  ep parameters an
37110 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  d SQLite will us
37120 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66  e whichever.** f
37130 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
37140 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
37150 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66  t of data transf
37160 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  ormation..** ^If
37170 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61   the xCallback a
37180 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20  rgument is NULL 
37190 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  then the collati
371a0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a  ng function is.*
371b0 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65  * deleted.  ^Whe
371c0 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20  n all collating 
371d0 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67  functions having
371e0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61   the same name a
371f0 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74  re deleted,.** t
37200 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  hat collation is
37210 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c   no longer usabl
37220 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f  e..**.** ^The co
37230 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
37240 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
37250 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79  oked with a copy
37260 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a   of the pArg .**
37270 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
37280 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69  a pointer and wi
37290 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69  th two strings i
372a0 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  n the encoding s
372b0 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
372c0 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75  he eTextRep argu
372d0 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61  ment.  The colla
372e0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
372f0 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20  st return an.** 
37300 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20  integer that is 
37310 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20  negative, zero, 
37320 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69  or positive.** i
37330 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69  f the first stri
37340 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c  ng is less than,
37350 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72   equal to, or gr
37360 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73  eater than the s
37370 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63  econd,.** respec
37380 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61  tively.  A colla
37390 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
373a0 73 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  st always return
373b0 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72   the same answer
373c0 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61  .** given the sa
373d0 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74  me inputs.  If t
373e0 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61  wo or more colla
373f0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
37400 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a  re registered.**
37410 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   to the same col
37420 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69  lation name (usi
37430 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65  ng different eTe
37440 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68  xtRep values) th
37450 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67  en all.** must g
37460 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e  ive an equivalen
37470 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e  t answer when in
37480 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76  voked with equiv
37490 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a  alent strings..*
374a0 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  * The collating 
374b0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62  function must ob
374c0 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ey the following
374d0 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20   properties for 
374e0 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41  all.** strings A
374f0 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a  , B, and C:.**.*
37500 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49  * <ol>.** <li> I
37510 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41  f A==B then B==A
37520 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d  ..** <li> If A==
37530 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20  B and B==C then 
37540 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  A==C..** <li> If
37550 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67   A&lt;B THEN B&g
37560 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  t;A..** <li> If 
37570 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b  A&lt;B and B&lt;
37580 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a  C then A&lt;C..*
37590 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </ol>.**.** If
375a0 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   a collating fun
375b0 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20  ction fails any 
375c0 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e  of the above con
375d0 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61  straints and tha
375e0 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66  t.** collating f
375f0 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69  unction is  regi
37600 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c  stered and used,
37610 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
37620 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  or of SQLite.** 
37630 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
37640 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37650 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37660 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b  n_v2() works lik
37670 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
37680 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20  _collation().** 
37690 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f  with the additio
376a0 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74  n that the xDest
376b0 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  roy callback is 
376c0 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20  invoked on pArg 
376d0 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c  when.** the coll
376e0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
376f0 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43  s deleted..** ^C
37700 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
37710 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77  ns are deleted w
37720 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65  hen they are ove
37730 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
37740 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  .** calls to the
37750 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
37760 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ion functions or
37770 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61   when the.** [da
37780 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37790 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69  n] is closed usi
377a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
377b0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  e()]..**.** ^The
377c0 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61   xDestroy callba
377d0 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e  ck is <u>not</u>
377e0 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a   called if the .
377f0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
37800 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
37810 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e   function fails.
37820 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
37830 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  hat invoke.** sq
37840 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
37850 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68  lation_v2() with
37860 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73   a non-NULL xDes
37870 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68  troy argument sh
37880 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74  ould .** check t
37890 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61  he return code a
378a0 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  nd dispose of th
378b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
378c0 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68  ta pointer.** th
378d0 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 20  emselves rather 
378e0 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53  than expecting S
378f0 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69  QLite to deal wi
37900 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a  th it for them..
37910 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 65  ** This is diffe
37920 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20  rent from every 
37930 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
37940 65 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63  erface.  The inc
37950 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69  onsistency .** i
37960 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75  s unfortunate bu
37970 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  t cannot be chan
37980 67 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  ged without brea
37990 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a  king backwards .
379a0 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
379b0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
379c0 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  :  [sqlite3_coll
379d0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
379e0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
379f0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
37a00 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
37a10 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
37a20 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ion(.  sqlite3*,
37a30 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
37a40 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
37a50 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
37a60 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
37a70 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
37a80 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
37a90 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
37aa0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
37ab0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
37ac0 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  2(.  sqlite3*, .
37ad0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
37ae0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
37af0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
37b00 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
37b10 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
37b20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
37b30 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20  const void*),.  
37b40 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
37b50 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
37b60 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
37b70 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  lation16(.  sqli
37b80 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76  te3*, .  const v
37b90 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e  oid *zName,.  in
37ba0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
37bb0 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
37bc0 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
37bd0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
37be0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
37bf0 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
37c00 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
37c10 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
37c20 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69  s.**.** ^To avoi
37c30 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69  d having to regi
37c40 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  ster all collati
37c50 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66  on sequences bef
37c60 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a  ore a database.*
37c70 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61  * can be used, a
37c80 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
37c90 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
37ca0 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
37cb0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
37cc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
37cd0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
37ce0 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65  ever an undefine
37cf0 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  d collation.** s
37d00 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69  equence is requi
37d10 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  red..**.** ^If t
37d20 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
37d30 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
37d40 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  the sqlite3_coll
37d50 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41  ation_needed() A
37d60 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  PI,.** then it i
37d70 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d  s passed the nam
37d80 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20  es of undefined 
37d90 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
37da0 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a  ces as strings.*
37db0 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  * encoded in UTF
37dc0 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  -8. ^If sqlite3_
37dd0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
37de0 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a  16() is used,.**
37df0 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70   the names are p
37e00 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20  assed as UTF-16 
37e10 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76  in machine nativ
37e20 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
37e30 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68   ^A call to eith
37e40 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c  er function repl
37e50 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e  aces the existin
37e60 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64  g collation-need
37e70 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ed callback..**.
37e80 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61  ** ^(When the ca
37e90 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
37ea0 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67  d, the first arg
37eb0 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20  ument passed is 
37ec0 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65  a copy.** of the
37ed0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
37ee0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   to sqlite3_coll
37ef0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f  ation_needed() o
37f00 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
37f10 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
37f20 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ).  The second a
37f30 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64  rgument is the d
37f40 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
37f50 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72  ction.  The thir
37f60 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
37f70 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
37f80 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
37f90 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  6BE],.** or [SQL
37fa0 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
37fb0 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
37fc0 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d  t desirable form
37fd0 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
37fe0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75  n.** sequence fu
37ff0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
38000 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
38010 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
38020 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71  me of the.** req
38030 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  uired collation 
38040 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a  sequence.)^.**.*
38050 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
38060 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72  unction should r
38070 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69  egister the desi
38080 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73  red collation us
38090 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
380a0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
380b0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
380c0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
380d0 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
380e0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
380f0 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69  tion_v2()]..*/.i
38100 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
38110 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73  tion_needed(.  s
38120 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
38130 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  *, .  void(*)(vo
38140 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
38150 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
38160 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  char*).);.int sq
38170 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
38180 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69  needed16(.  sqli
38190 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  te3*, .  void*,.
381a0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
381b0 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
381c0 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64  xtRep,const void
381d0 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51  *).);..#ifdef SQ
381e0 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f  LITE_HAS_CODEC./
381f0 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
38200 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
38210 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
38220 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
38230 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
38240 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
38250 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
38260 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
38270 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
38280 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
38290 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
382a0 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
382b0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
382c0 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71  qlite3_key(.  sq
382d0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
382e0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
382f0 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
38300 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
38310 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
38320 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
38330 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20  e key */.);.int 
38340 73 71 6c 69 74 65 33 5f 6b 65 79 5f 76 32 28 0a  sqlite3_key_v2(.
38350 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
38360 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38370 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
38380 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
38390 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e  const char *zDbN
383a0 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20 2f  ame,           /
383b0 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  * Name of the da
383c0 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
383d0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
383e0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
383f0 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  e key */.);../*.
38400 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65  ** Change the ke
38410 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74  y on an open dat
38420 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63  abase.  If the c
38430 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
38440 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70  is not.** encryp
38450 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ted, this routin
38460 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69  e will encrypt i
38470 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f  t.  If pNew==0 o
38480 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a  r nNew==0, the.*
38490 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  * database is de
384a0 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  crypted..**.** T
384b0 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
384c0 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
384d0 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
384e0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
384f0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
38500 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
38510 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74  3_rekey(.  sqlit
38520 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
38530 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
38540 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
38550 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
38560 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
38570 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e  Key     /* The n
38580 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74  ew key */.);.int
38590 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 5f 76   sqlite3_rekey_v
385a0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
385b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
385c0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
385d0 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
385e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
385f0 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20  DbName,         
38600 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
38610 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
38620 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
38630 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
38640 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a   The new key */.
38650 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  );../*.** Specif
38660 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
38670 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 64   key for a SEE d
38680 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73  atabase.  Unless
38690 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20   .** activated, 
386a0 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20  none of the SEE 
386b0 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
386c0 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  rk..*/.void sqli
386d0 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65  te3_activate_see
386e0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
386f0 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20  zPassPhrase     
38700 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e     /* Activation
38710 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65   phrase */.);.#e
38720 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c  ndif..#ifdef SQL
38730 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44  ITE_ENABLE_CEROD
38740 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
38750 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
38760 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61  y for a CEROD da
38770 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20  tabase.  Unless 
38780 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e  .** activated, n
38790 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44  one of the CEROD
387a0 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77   routines will w
387b0 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ork..*/.void sql
387c0 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65  ite3_activate_ce
387d0 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  rod(.  const cha
387e0 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
387f0 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
38800 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
38810 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43